leaf-framework 0.10.22__tar.gz → 0.11.0__tar.gz

{leaf_framework-0.10.22 → leaf_framework-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leaf-framework
-Version: 0.10.22
+Version: 0.11.0
 Summary: Lightweight Adapter Framework (LEAF)
 License: Apache-2.0
 License-File: LICENSE
@@ -12,18 +12,16 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: aioredis (>=2.0.1,<2.1.0)
-Requires-Dist: cairosvg (>=2.8.2,<3.0.0)
-Requires-Dist: dateparser (>=1.3.0,<1.4.0)
+Requires-Dist: cairosvg (>=2.9.1,<3.0.0)
+Requires-Dist: dateparser (>=1.4.3,<1.5.0)
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
-Requires-Dist: influxobject (>=0.0.13)
-Requires-Dist: nicegui (>=3.16.0,<3.17.0)
+Requires-Dist: leafobject (>=0.0.14,<0.0.15)
+Requires-Dist: nicegui (>=3.18.0,<3.19.0)
 Requires-Dist: paho-mqtt (>=2.1.0,<2.2.0)
-Requires-Dist: pillow (>=12.1.1,<13.0.0)
+Requires-Dist: pillow (>=13.0.0,<14.0.0)
 Requires-Dist: pyyaml (>=6.0.3,<6.1.0)
-Requires-Dist: redis (>=7.2.0,<7.3.0)
 Requires-Dist: requests (>=2.34.2,<2.35.0)
-Requires-Dist: watchdog (>=6.0.0,<6.1.0)
+Requires-Dist: watchdog (>=7.0.0,<7.1.0)
 Project-URL: Documentation, https://leaf-framework.org
 Project-URL: Repository, https://gitlab.com/leaf-framework/leaf
 Description-Content-Type: text/markdown
@@ -44,13 +42,17 @@ leaf
 
 LEAF automatically shows a **desktop control panel** on desktop systems, making it easy to see if the application is running and where to access it.
 
+## Password for the web interface
+
+The web interface is open by default. When it runs where others can reach it (a Kubernetes pod with an ingress, a shared server), set `LEAF_UI_PASSWORD`: every page then asks for that password once, on a login form password managers can fill, and keeps the browser logged in for 30 days. Changing the password logs every browser out. It sends the password over the wire, so serve the interface over HTTPS.
+
 ## Updating
 
 LEAF checks PyPI for a newer release one hour after it starts, and weekly from then on -- never at startup, so a restart simply re-arms the one-hour delay. When a newer version exists, an **update badge** appears next to the version number in the web interface header; clicking it offers to install the update and restart LEAF.
 
 To check without waiting for the schedule, **click the version number** in the header. The result appears as a banner: green when this install is current, amber when a newer release exists, red when PyPI could not be reached.
 
-Set `LEAF_DISABLE_UPDATE_CHECK=1` to switch the check off entirely. Installs running from a source checkout are told about the new version but never overwritten -- update those with `git pull`. To update by hand:
+Set `LEAF_DISABLE_UPDATE_CHECK=1` to switch the check off entirely. Set `LEAF_DISABLE_ADAPTER_INSTALL=1` to stop the web interface from installing or uninstalling adapters, e.g. on a shared deployment whose adapters come from its image. Installs running from a source checkout are told about the new version but never overwritten -- update those with `git pull`. To update by hand:
 
 ```bash
 pip install --upgrade leaf-framework

{leaf_framework-0.10.22 → leaf_framework-0.11.0}/README.md

@@ -14,13 +14,17 @@ leaf
 
 LEAF automatically shows a **desktop control panel** on desktop systems, making it easy to see if the application is running and where to access it.
 
+## Password for the web interface
+
+The web interface is open by default. When it runs where others can reach it (a Kubernetes pod with an ingress, a shared server), set `LEAF_UI_PASSWORD`: every page then asks for that password once, on a login form password managers can fill, and keeps the browser logged in for 30 days. Changing the password logs every browser out. It sends the password over the wire, so serve the interface over HTTPS.
+
 ## Updating
 
 LEAF checks PyPI for a newer release one hour after it starts, and weekly from then on -- never at startup, so a restart simply re-arms the one-hour delay. When a newer version exists, an **update badge** appears next to the version number in the web interface header; clicking it offers to install the update and restart LEAF.
 
 To check without waiting for the schedule, **click the version number** in the header. The result appears as a banner: green when this install is current, amber when a newer release exists, red when PyPI could not be reached.
 
-Set `LEAF_DISABLE_UPDATE_CHECK=1` to switch the check off entirely. Installs running from a source checkout are told about the new version but never overwritten -- update those with `git pull`. To update by hand:
+Set `LEAF_DISABLE_UPDATE_CHECK=1` to switch the check off entirely. Set `LEAF_DISABLE_ADAPTER_INSTALL=1` to stop the web interface from installing or uninstalling adapters, e.g. on a shared deployment whose adapters come from its image. Installs running from a source checkout are told about the new version but never overwritten -- update those with `git pull`. To update by hand:
 
 ```bash
 pip install --upgrade leaf-framework

leaf_framework-0.11.0/leaf/adapters/control_spec.py

@@ -0,0 +1,176 @@
+"""
+The controls an adapter declares in its device.json, narrowed by an instance's control_limits.
+
+Every control message, from MQTT or the UI, is checked against them before the controller sees it,
+so the limits hold however the message arrives. An adapter that declares no controls is not checked.
+"""
+
+import json
+import os
+from typing import cast
+
+import yaml
+from leafobject import LeafPoint  # pyright: ignore[reportMissingTypeStubs]
+
+Control = dict[str, object]
+
+
+def read_controls(adapter_dir: str) -> list[Control]:
+    """The "controls" list from device.json (or device.yaml) in an adapter's package, or []."""
+    for name in ("device.json", "device.yaml"):
+        path = os.path.join(adapter_dir, name)
+        if not os.path.exists(path):
+            continue
+        with open(path) as f:
+            if name.endswith(".json"):
+                device = cast(object, json.load(f))
+            else:
+                device = cast(object, yaml.safe_load(f))
+        if not isinstance(device, dict):
+            return []
+        controls = cast(dict[str, object], device).get("controls")
+        if not isinstance(controls, list):
+            return []
+        return [cast(Control, c) for c in cast(list[object], controls) if isinstance(c, dict)]
+    return []
+
+
+def as_number(value: object) -> float | None:
+    """value as a float, or None when it is not a number (bools are not numbers here)."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value)
+
+
+def _narrow(control: Control, limit: object) -> Control:
+    """The control with the instance's min/max, which may only tighten the adapter's own range."""
+    metric = control["metric"]
+    if control.get("type") != "number" or not isinstance(limit, dict):
+        raise ValueError(f"control_limits for {metric} need a number control and min/max keys")
+    narrowed = dict(control)
+    for key, value in cast(dict[str, object], limit).items():
+        bound = as_number(value)
+        if key not in ("min", "max") or bound is None:
+            raise ValueError(f"control_limits for {metric}: {key} must be min or max with a number")
+        adapter_bound = as_number(control.get(key))
+        if adapter_bound is not None and (
+            (key == "min" and bound < adapter_bound) or (key == "max" and bound > adapter_bound)
+        ):
+            raise ValueError(
+                f"control_limits for {metric}: {key} {bound} is outside the adapter's {key} {adapter_bound}"
+            )
+        narrowed[key] = bound
+    return narrowed
+
+
+def apply_limits(controls: list[Control], limits: dict[str, object]) -> list[Control]:
+    """Controls with an instance's control_limits applied; ValueError for limits that do not fit."""
+    known = {str(c.get("metric")) for c in controls}
+    unknown = sorted(set(limits) - known)
+    if unknown:
+        raise ValueError(f"control_limits for undeclared controls: {', '.join(unknown)}")
+    result: list[Control] = []
+    for control in controls:
+        metric = str(control.get("metric"))
+        if metric in limits:
+            result.append(_narrow(control, limits[metric]))
+        else:
+            result.append(control)
+    return result
+
+
+def _check_number(control: Control, value: object) -> None:
+    number = as_number(value)
+    if number is None:
+        raise ValueError(f"{control['metric']} needs a number, got {value!r}")
+    low = as_number(control.get("min"))
+    high = as_number(control.get("max"))
+    if low is not None and number < low:
+        raise ValueError(f"{control['metric']} = {number} is below its minimum {low}")
+    if high is not None and number > high:
+        raise ValueError(f"{control['metric']} = {number} is above its maximum {high}")
+
+
+def _metric_and_value(data: str) -> tuple[object, object]:
+    """tags.metric and fields.value of a LeafPoint control message."""
+    point = cast(object, json.loads(data))
+    if not isinstance(point, dict):
+        raise ValueError("a control message must be a LeafPoint JSON object")
+    point_dict = cast(dict[str, object], point)
+    tags = point_dict.get("tags")
+    fields = point_dict.get("fields")
+    if not isinstance(tags, dict) or not isinstance(fields, dict):
+        raise ValueError("a control message needs tags and fields")
+    return cast(dict[str, object], tags).get("metric"), cast(dict[str, object], fields).get("value")
+
+
+def check_control(controls: list[Control], data: str) -> None:
+    """Raise ValueError unless the LeafPoint in data sets a declared metric to an allowed value."""
+    if not controls:
+        return
+    metric, value = _metric_and_value(data)
+    control = next((c for c in controls if c.get("metric") == metric), None)
+    if control is None:
+        raise ValueError(f"{metric!r} is not a declared control")
+    if value is not None and value == control.get("reset"):
+        return
+    kind = control.get("type")
+    if kind == "number":
+        _check_number(control, value)
+    elif kind == "choice":
+        options = control.get("options")
+        if not isinstance(options, list) or value not in cast(list[object], options):
+            raise ValueError(f"{metric} cannot be set to {value!r}")
+    elif not isinstance(value, str) or not value:
+        raise ValueError(f"{metric} needs a text value")
+
+
+def _part(point: dict[str, object], key: str) -> dict[str, object]:
+    """A copy of point[key] when it is a dict, else an empty dict."""
+    part = point.get(key)
+    if isinstance(part, dict):
+        return dict(cast(dict[str, object], part))
+    return {}
+
+
+def _field_value(value: object) -> int | float | str:
+    """value as a LeafPoint field allows it: a number or text, anything else as its JSON."""
+    if isinstance(value, (int, float, str)):
+        return value
+    return json.dumps(value)
+
+
+def result_record(data: str, source: str, error: Exception | None = None) -> dict[str, object]:
+    """
+    A control message as the LeafPoint LEAF publishes on <control topic>/result, so that what was
+    sent to the equipment is stored with the measurements.
+
+    source ("ui" or "mqtt"), status ("applied" or "rejected") and a rejection's "error" are tags,
+    for consumers to filter on. Built as a leafobject LeafPoint, so tags are text and there is
+    always a field: a message without fields keeps its raw text in "message".
+    """
+    point: dict[str, object] = {}
+    try:
+        parsed = cast(object, json.loads(data))
+        if isinstance(parsed, dict):
+            point = cast(dict[str, object], parsed)
+    except ValueError:
+        pass
+    tags: dict[str, str] = {}
+    for key, value in _part(point, "tags").items():
+        tags[key] = str(value)
+    fields: dict[str, int | float | str] = {}
+    for key, value in _part(point, "fields").items():
+        fields[key] = _field_value(value)
+    tags["source"] = source
+    tags["status"] = "applied"
+    if error is not None:
+        tags["status"] = "rejected"
+        tags["error"] = str(error)
+    if not fields:
+        fields["message"] = data
+    record = LeafPoint()
+    record.set_measurement(str(point.get("measurement", "control")))
+    record.set_tags(tags)
+    record.set_fields(fields)
+    return {**record.to_json()}

{leaf_framework-0.10.22 → leaf_framework-0.11.0}/leaf/adapters/equipment_adapter.py

@@ -4,6 +4,7 @@ from abc import ABC, abstractmethod
 from threading import Event
 from typing import Any
 
+from leaf.adapters.control_spec import Control, check_control, result_record
 from leaf.error_handler import exceptions
 from leaf.error_handler.error_holder import ErrorHolder
 from leaf.error_handler.exceptions import LEAFError
@@ -119,6 +120,29 @@ class AbstractInterpreter(ABC):
             raise exception
 
 
+class AbstractController(ABC):
+    """
+    Base class for an adapter's controller.py.
+
+    When an instance is configured with ``control: true``, LEAF subscribes to
+    <root>/<organisation>/<department>/<adapter_id>/<instance_id>/control and
+    hands every message to control(). ``self.adapter`` is the running adapter.
+    """
+
+    def __init__(self) -> None:
+        self.adapter: EquipmentAdapter | None = None
+
+    @abstractmethod
+    def control(self, topic: str, data: str) -> None:
+        """
+        Act on a control message.
+
+        Args:
+            topic (str): The control topic the message arrived on.
+            data (str): Raw message payload.
+        """
+
+
 class EquipmentAdapter(ABC):
     """
     Base class for all equipment adapters.
@@ -201,6 +225,82 @@ class EquipmentAdapter(ABC):
             self._external_process.set_interpreter(interpreter)
             self._external_watcher.add_callback(self._external_process.process_input)
 
+        self._controller: AbstractController | None = None
+        self._controls: list[Control] = []
+
+    def set_controller(self, controller: AbstractController, controls: list[Control] | None = None) -> None:
+        """
+        Attach a controller; its control() runs for each message on the instance's control topic.
+
+        Messages are first checked against controls (from device.json, with the instance's limits).
+        """
+        controller.adapter = self
+        self._controller = controller
+        self._controls = controls or []
+
+    @property
+    def controls(self) -> list[Control]:
+        """The declared controls with this instance's limits, as used to check control messages."""
+        return self._controls
+
+    def _on_control(self, topic: str, data: str) -> None:
+        # Runs on the MQTT network thread, so never let an exception escape.
+        if self._controller is None:
+            return
+        try:
+            self._logger.info(f"Control message on {topic}: {data}")
+            check_control(self._controls, data)
+            self._controller.control(topic, data)
+        except Exception as e:
+            # The error holder reports it later; log it now so the sender can see why nothing happened
+            self._logger.warning(f"Control message on {topic} rejected: {e}")
+            self._report_control(topic, data, "mqtt", e)
+            self._handle_exception(exceptions.AdapterLogicError(f"Controller failed: {e}"))
+            return
+        self._report_control(topic, data, "mqtt")
+
+    def has_controller(self) -> bool:
+        """True when the instance runs with control: true and a controller is attached."""
+        return self._controller is not None
+
+    @property
+    def metadata_manager(self) -> MetadataManager:
+        """Instance and equipment metadata, e.g. to tag control points sent from the UI."""
+        return self._metadata_manager
+
+    def send_control(self, data: str) -> None:
+        """
+        Hand a control message from inside LEAF (the UI) to the controller, as if it came in on the control topic.
+
+        Errors are reported like those of messages from MQTT, and also propagate so the caller can show them.
+        """
+        if self._controller is None:
+            raise exceptions.AdapterLogicError("this instance has no controller; set control: true")
+        # Topic builders are generated at runtime, so the checker sees them as Any
+        topic = str(self._metadata_manager.control())  # pyright: ignore[reportAny]
+        self._logger.info(f"Control message from the UI on {topic}: {data}")
+        try:
+            check_control(self._controls, data)
+            self._controller.control(topic, data)
+        except Exception as e:
+            # Reported like a control message from MQTT, so it also reaches the error topic
+            self._report_control(topic, data, "ui", e)
+            self._handle_exception(exceptions.AdapterLogicError(f"Controller failed: {e}"))
+            raise
+        self._report_control(topic, data, "ui")
+
+    def _report_control(self, topic: str, data: str, source: str, error: Exception | None = None) -> None:
+        """Publish what happened to a control message on <control topic>/result, so it is stored with the data."""
+        # Never let the record break the command it describes
+        try:
+            _ = self._output.transmit(f"{topic}/result", result_record(data, source, error))
+        except Exception as e:
+            self._logger.warning(f"Could not publish the control record for {topic}: {e}")
+
+    def _subscribe_control(self) -> None:
+        if self._controller is not None:
+            self._output.subscribe(self._metadata_manager.control(), self._on_control)
+
     def is_running(self) -> bool:
         """
         Check if the adapter is actively running.
@@ -233,6 +333,7 @@ class EquipmentAdapter(ABC):
             if self._external_watcher:
                 self._external_watcher.start()
             self._output.on_adapter_ready(self._metadata_manager)
+            self._subscribe_control()
 
             self._stop_event.clear()
             # Expose adapter on all channels.
@@ -316,6 +417,8 @@ class EquipmentAdapter(ABC):
         """
         self._stop_event.set()
         self._output.on_adapter_stop(self._metadata_manager)
+        if self._controller is not None:
+            self._output.unsubscribe(self._metadata_manager.control())
         if self._watcher.is_running():
             self._watcher.stop()
 
@@ -348,7 +451,8 @@ class EquipmentAdapter(ABC):
                 return self.stop()
 
             error_json = error.to_json()
-            for process in self._processes:
+            # Every process publishes to the instance's one error topic, so one of them is enough
+            for process in self._processes[:1]:
                 process.transmit_error(error_json)
                 time.sleep(0.1)
 

{leaf_framework-0.10.22 → leaf_framework-0.11.0}/leaf/config/configuration.yaml

@@ -26,24 +26,16 @@ OUTPUTS:
 #   protocol: v3   #OPTIONAL expects "v3" "v5"
 #   transport: tcp #OPTIONAL expects "tcp", "websockets", "unix"
 #   tls: False     #OPTIONAL expects True, False
-#   fallback: SQL  #OPTIONAL expects "SQL", "KEYDB", "FILE"
+#   fallback: FILE #OPTIONAL expects "SQL", "FILE"
 
 # SQL output requires 'filename' of database 
 # and optionally an alternative 'fallback' output
 #  - plugin: SQL
 #    filename: messages.db
-#    fallback: KEYDB #OPTIONAL expects "MQTT", "KEYDB", "FILE"
-
-# KEYDB output requires 'host', 'port', 'db'
-# and optionally an alternative 'fallback' output
-#  - plugin: KEYDB
-#    host: localhost
-#    port: 6379
-#    db: 0
-#    fallback: FILE #OPTIONAL expects "MQTT", "SQL", "FILE"
+#    fallback: FILE #OPTIONAL expects "MQTT", "FILE"
 
 # FILE output requires 'filename'
 # and optionally an alternative 'fallback' output
 #  - plugin: FILE
 #    filename: local.json
-#    fallback: FILE #OPTIONAL expects "MQTT", "SQL", "KEYDB"
+#    fallback: SQL #OPTIONAL expects "MQTT", "SQL"

{leaf_framework-0.10.22 → leaf_framework-0.11.0}/leaf/data/marketplace.yaml

@@ -3,7 +3,7 @@
 
 - adapter_id: Table
   image: "./images/table.png"
-  description: "File conversion module to parse tabular data from various file formats into InfluxObject messages."
+  description: "File conversion module to parse tabular data from various file formats into LeafPoint messages."
   equipment_data:
     version: "1.0"
     manufacturer: LEAF
@@ -233,6 +233,10 @@
     application: Monitoring
   # requirements:
   repo_url: https://git.wur.nl/leaf/adapters/leaf-ramsmart.git
+  # Private repository: installed with a username and token handed out per user. One deploy
+  # token (read_repository, with an expiry) per person, named after them; lost → revoke and reissue.
+  access: restricted
+  request_access: mailto:access@leaf-framework.org?subject=Access%20to%20LEAF-RAMSMART
   name: LEAF-RAMSMART
 - adapter_id: BluetoothScanner
   image: icon:bi-bluetooth

{leaf_framework-0.10.22 → leaf_framework-0.11.0}/leaf/modules/input_modules/http_watcher.py

@@ -41,19 +41,22 @@ class URLState:
         Returns:
             Optional[dict]: Parsed JSON if the response is new; else None.
         """
-        if response.headers.get("ETag") == self.etag:
+        etag = response.headers.get("ETag")
+        last_modified = response.headers.get("Last-Modified")
+        # Only a header the server sent can say "unchanged"; two missing ones are not a match
+        if etag is not None and etag == self.etag:
             return None
-        if response.headers.get("Last-Modified") == self.last_modified:
+        if last_modified is not None and last_modified == self.last_modified:
             return None
 
         current_data = response.json()
 
-        if self.etag is None and self.last_modified is None:
+        if etag is None and last_modified is None:
             if current_data == self.previous_data:
                 return None
 
-        self.etag = response.headers.get("ETag")
-        self.last_modified = response.headers.get("Last-Modified")
+        self.etag = etag
+        self.last_modified = last_modified
         self.previous_data = current_data
 
         return current_data

{leaf_framework-0.10.22 → leaf_framework-0.11.0}/leaf/modules/output_modules/mqtt.py

@@ -2,8 +2,9 @@ import json
 import re
 import threading
 import time
+from collections.abc import Callable
 from socket import gaierror
-from typing import Any, Literal
+from typing import Any, Literal, cast
 
 import paho.mqtt.client as mqtt
 from paho.mqtt.enums import CallbackAPIVersion
@@ -102,6 +103,8 @@ class MQTT(OutputModule):
         self.messages: dict[str, list[str]] = {}
         self.sending_success: dict[str, bool] = {}
         self._sanitized_topic_warned: set[str] = set()
+        # Topics with a callback; kept so they are resubscribed after a reconnect (clean session).
+        self._subscriptions: dict[str, Callable[[str, str], None]] = {}
         # paho's connect() returns once the socket is open and the CONNECT
         # packet is sent, but the broker's CONNACK (which is what actually
         # flips is_connected() to True) is only processed once loop_start()'s
@@ -257,6 +260,8 @@ class MQTT(OutputModule):
                 return self.fallback(topic, data)
         if data == "":
             data = {}
+        # The topic store keeps the dict, which the Monitoring plot reads points from
+        message = cast(object, data)
         if isinstance(data, (dict, list)):
             data = json.dumps(data)
 
@@ -299,7 +304,7 @@ class MQTT(OutputModule):
         # Reset global failure counter only after successful transmission AND fallback processing
         OutputModule.reset_failure_count()
 
-        self.store_latest(topic, data)
+        self.store_latest(topic, message)
 
         # Transmit to parallel outputs (best-effort, failures don't affect primary result)
         self.transmit_to_parallels(topic, data)
@@ -365,6 +370,8 @@ class MQTT(OutputModule):
             self._handle_exception(ClientUnreachableError(f"Connection refused: {message}", output_module=self))
             return
 
+        for topic in list(self._subscriptions):
+            self.client.subscribe(topic)
         self._connected_event.set()
 
     def on_connect_fail(
@@ -453,6 +460,9 @@ class MQTT(OutputModule):
         if topic not in self.messages:
             self.messages[topic] = []
         self.messages[topic].append(payload)
+        callback = self._subscriptions.get(topic)
+        if callback is not None:
+            callback(topic, payload)
 
     def reset_messages(self) -> None:
         """
@@ -460,17 +470,20 @@ class MQTT(OutputModule):
         """
         self.messages = {}
 
-    def subscribe(self, topic: str) -> str:
+    def subscribe(self, topic: str, callback: Callable[[str, str], None] | None = None) -> str:
         """
         Subscribe to a topic on the MQTT broker.
 
         Args:
             topic (str): The topic to subscribe to.
+            callback (Optional[Callable]): Called with (topic, payload) for each message on this exact topic.
 
         Returns:
             str: The subscribed topic.
         """
         logger.info(f"Subscribing to {topic}")
+        if callback is not None:
+            self._subscriptions[topic] = callback
         self.client.subscribe(topic)
         return topic
 
@@ -485,6 +498,7 @@ class MQTT(OutputModule):
             str: The unsubscribed topic.
         """
         logger.info(f"Unsubscribing from {topic}")
+        self._subscriptions.pop(topic, None)
         self.client.unsubscribe(topic)
         return topic
 
@@ -513,7 +527,7 @@ class MQTT(OutputModule):
         Retrieve and remove a stored message from the fallback.
 
         MQTT does not buffer messages locally, so this delegates to the fallback
-        module (e.g., KeyDB or FILE) to retrieve buffered messages.
+        module (e.g., SQL or FILE) to retrieve buffered messages.
 
         Args:
             key (Optional[str]): A key for which to pop data. Defaults to None.

{leaf_framework-0.10.22 → leaf_framework-0.11.0}/leaf/modules/output_modules/output_module.py

@@ -1,5 +1,6 @@
 import time
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from typing import Any, Optional
 
 from leaf.error_handler.error_holder import ErrorHolder
@@ -119,15 +120,27 @@ class OutputModule(ABC):
         if self._fallback is not None:
             self._fallback.flush(topic)
 
-    def subscribe(self, topic: str) -> None:
+    def subscribe(self, topic: str, callback: Callable[[str, str], None] | None = None) -> None:
         """
         Listen on the specified topic if supported by the module.
 
         Args:
             topic (str): Topic to subscribe to.
+            callback (Optional[Callable]): Called with (topic, payload) for each message, if supported.
         """
         if self._fallback is not None:
-            self._fallback.subscribe(topic)
+            self._fallback.subscribe(topic, callback)
+
+    def unsubscribe(self, topic: str) -> str | None:
+        """
+        Stop listening on the specified topic if supported by the module.
+
+        Args:
+            topic (str): Topic to unsubscribe from.
+        """
+        if self._fallback is not None:
+            return self._fallback.unsubscribe(topic)
+        return None
 
     def fallback(self, topic: str, data: str | dict[Any, Any] | None = None) -> bool:
         """