mmrelay 1.1.3__py3-none-any.whl → 1.2.0__py3-none-any.whl

mmrelay/message_queue.py

@@ -13,18 +13,18 @@ from dataclasses import dataclass
 from queue import Empty, Queue
 from typing import Callable, Optional
 
+from mmrelay.constants.database import DEFAULT_MSGS_TO_KEEP
+from mmrelay.constants.network import MINIMUM_MESSAGE_DELAY
+from mmrelay.constants.queue import (
+    DEFAULT_MESSAGE_DELAY,
+    MAX_QUEUE_SIZE,
+    QUEUE_HIGH_WATER_MARK,
+    QUEUE_MEDIUM_WATER_MARK,
+)
 from mmrelay.log_utils import get_logger
 
 logger = get_logger(name="MessageQueue")
 
-# Default message delay in seconds (minimum 2.0 due to firmware constraints)
-DEFAULT_MESSAGE_DELAY = 2.2
-
-# Queue size configuration
-MAX_QUEUE_SIZE = 100
-QUEUE_HIGH_WATER_MARK = 75  # 75% of MAX_QUEUE_SIZE
-QUEUE_MEDIUM_WATER_MARK = 50  # 50% of MAX_QUEUE_SIZE
-
 
 @dataclass
 class QueuedMessage:
@@ -61,20 +61,20 @@ class MessageQueue:
 
     def start(self, message_delay: float = DEFAULT_MESSAGE_DELAY):
         """
-        Starts the message queue processor with the specified minimum delay between messages.
+        Start the message queue processor with a specified minimum delay between messages.
 
-        Enforces a minimum delay of 2.0 seconds due to firmware requirements. If the event loop is running, the processor task is started immediately; otherwise, startup is deferred until the event loop becomes available.
+        If the provided delay is below the firmware-enforced minimum, the minimum is used instead. The processor task is started immediately if the asyncio event loop is running; otherwise, startup is deferred until the event loop becomes available.
         """
         with self._lock:
             if self._running:
                 return
 
             # Validate and enforce firmware minimum
-            if message_delay < 2.0:
+            if message_delay < MINIMUM_MESSAGE_DELAY:
                 logger.warning(
-                    f"Message delay {message_delay}s below firmware minimum (2.0s), using 2.0s"
+                    f"Message delay {message_delay}s below firmware minimum ({MINIMUM_MESSAGE_DELAY}s), using {MINIMUM_MESSAGE_DELAY}s"
                 )
-                self._message_delay = 2.0
+                self._message_delay = MINIMUM_MESSAGE_DELAY
             else:
                 self._message_delay = message_delay
             self._running = True
@@ -372,13 +372,13 @@ class MessageQueue:
 
     def _handle_message_mapping(self, result, mapping_info):
         """
-        Stores and prunes message mapping information after a message is sent.
+        Update the message mapping database with information about a sent message and prune old mappings if configured.
 
         Parameters:
             result: The result object from the send function, expected to have an `id` attribute.
-            mapping_info (dict): Dictionary containing mapping details such as `matrix_event_id`, `room_id`, `text`, and optional `meshnet` and `msgs_to_keep`.
+            mapping_info (dict): Contains mapping details such as `matrix_event_id`, `room_id`, `text`, and optionally `meshnet` and `msgs_to_keep`.
 
-        This method updates the message mapping database with the new mapping and prunes old mappings if configured.
+        If required mapping fields are present, stores the mapping and prunes old entries based on the specified or default retention count.
         """
         try:
             # Import here to avoid circular imports
@@ -402,7 +402,7 @@ class MessageQueue:
                 logger.debug(f"Stored message map for meshtastic_id: {result.id}")
 
                 # Handle pruning if configured
-                msgs_to_keep = mapping_info.get("msgs_to_keep", 500)
+                msgs_to_keep = mapping_info.get("msgs_to_keep", DEFAULT_MSGS_TO_KEEP)
                 if msgs_to_keep > 0:
                     prune_message_map(msgs_to_keep)
 

mmrelay/plugin_loader.py

@@ -16,68 +16,82 @@ sorted_active_plugins = []
 plugins_loaded = False
 
 
-def get_custom_plugin_dirs():
+def _reset_caches_for_tests():
+    """
+    Reset the global plugin loader caches to their initial state for testing purposes.
+
+    Clears cached plugin instances and loading state to ensure test isolation and prevent interference between test runs.
     """
-    Returns a list of directories to check for custom plugins in order of priority:
-    1. User directory (~/.mmrelay/plugins/custom)
-    2. Local directory (plugins/custom) for backward compatibility
+    global sorted_active_plugins, plugins_loaded
+    sorted_active_plugins = []
+    plugins_loaded = False
+
+
+def _get_plugin_dirs(plugin_type):
+    """
+    Return a prioritized list of directories for the specified plugin type, including user and local plugin directories if accessible.
+
+    Parameters:
+        plugin_type (str): Either "custom" or "community", specifying the type of plugins.
+
+    Returns:
+        list: List of plugin directories to search, with the user directory first if available, followed by the local directory for backward compatibility.
     """
     dirs = []
 
     # Check user directory first (preferred location)
-    user_dir = os.path.join(get_base_dir(), "plugins", "custom")
-    os.makedirs(user_dir, exist_ok=True)
-    dirs.append(user_dir)
+    user_dir = os.path.join(get_base_dir(), "plugins", plugin_type)
+    try:
+        os.makedirs(user_dir, exist_ok=True)
+        dirs.append(user_dir)
+    except (OSError, PermissionError) as e:
+        logger.warning(f"Cannot create user plugin directory {user_dir}: {e}")
 
     # Check local directory (backward compatibility)
-    local_dir = os.path.join(get_app_path(), "plugins", "custom")
-    dirs.append(local_dir)
+    local_dir = os.path.join(get_app_path(), "plugins", plugin_type)
+    try:
+        os.makedirs(local_dir, exist_ok=True)
+        dirs.append(local_dir)
+    except (OSError, PermissionError):
+        # Skip local directory if we can't create it (e.g., in Docker)
+        logger.debug(f"Cannot create local plugin directory {local_dir}, skipping")
 
     return dirs
 
 
-def get_community_plugin_dirs():
+def get_custom_plugin_dirs():
     """
-    Returns a list of directories to check for community plugins in order of priority:
-    1. User directory (~/.mmrelay/plugins/community)
-    2. Local directory (plugins/community) for backward compatibility
+    Return the list of directories to search for custom plugins, ordered by priority.
+
+    The directories include the user-specific custom plugins directory and a local directory for backward compatibility.
     """
-    dirs = []
+    return _get_plugin_dirs("custom")
 
-    # Check user directory first (preferred location)
-    user_dir = os.path.join(get_base_dir(), "plugins", "community")
-    os.makedirs(user_dir, exist_ok=True)
-    dirs.append(user_dir)
 
-    # Check local directory (backward compatibility)
-    local_dir = os.path.join(get_app_path(), "plugins", "community")
-    dirs.append(local_dir)
+def get_community_plugin_dirs():
+    """
+    Return the list of directories to search for community plugins, ordered by priority.
 
-    return dirs
+    The directories include the user-specific community plugins directory and a local directory for backward compatibility.
+    """
+    return _get_plugin_dirs("community")
 
 
 def clone_or_update_repo(repo_url, ref, plugins_dir):
-    """Clone or update a Git repository for community plugins.
+    """
+    Clone or update a community plugin Git repository and ensure its dependencies are installed.
+
+    Attempts to clone the repository at the specified branch or tag, or update it if it already exists. Handles switching between branches and tags, falls back to default branches if needed, and installs Python dependencies from `requirements.txt` using either pip or pipx. Logs errors and warnings for any issues encountered.
 
-    Args:
-        repo_url (str): Git repository URL to clone/update
+    Parameters:
+        repo_url (str): The URL of the Git repository to clone or update.
         ref (dict): Reference specification with keys:
-                   - type: "tag" or "branch"
-                   - value: tag name or branch name
-        plugins_dir (str): Directory where the repository should be cloned
+            - type: "tag" or "branch"
+            - value: The tag or branch name to use.
+        plugins_dir (str): Directory where the repository should be cloned or updated.
 
     Returns:
-        bool: True if successful, False if clone/update failed
-
-    Handles complex Git operations including:
-    - Cloning new repositories with specific tags/branches
-    - Updating existing repositories and switching refs
-    - Installing requirements.txt dependencies via pip or pipx
-    - Fallback to default branches (main/master) when specified ref fails
-    - Robust error handling and logging
-
-    The function automatically installs Python dependencies if a requirements.txt
-    file is found in the repository root.
+        bool: True if the repository was successfully cloned or updated and dependencies were handled; False if any critical error occurred.
     """
     # Extract the repository name from the URL
     repo_name = os.path.splitext(os.path.basename(repo_url.rstrip("/")))[0]
@@ -326,7 +340,13 @@ def clone_or_update_repo(repo_url, ref, plugins_dir):
         # Repository doesn't exist yet, clone it
         try:
             os.makedirs(plugins_dir, exist_ok=True)
+        except (OSError, PermissionError) as e:
+            logger.error(f"Cannot create plugin directory {plugins_dir}: {e}")
+            logger.error(f"Skipping repository {repo_name} due to permission error")
+            return False
 
+        # Now try to clone the repository
+        try:
             # If it's a default branch, just clone it directly
             if is_default_branch:
                 try:
@@ -519,26 +539,17 @@ def clone_or_update_repo(repo_url, ref, plugins_dir):
 
 
 def load_plugins_from_directory(directory, recursive=False):
-    """Load plugin classes from Python files in a directory.
-
-    Args:
-        directory (str): Directory path to search for plugin files
-        recursive (bool): Whether to search subdirectories recursively
-
-    Returns:
-        list: List of instantiated plugin objects found in the directory
+    """
+    Dynamically loads and instantiates plugin classes from Python files in a specified directory.
 
-    Scans for .py files and attempts to import each as a module. Looks for
-    a 'Plugin' class in each module and instantiates it if found.
+    Scans the given directory (and subdirectories if `recursive` is True) for `.py` files, importing each as a module and instantiating its `Plugin` class if present. Automatically attempts to install missing dependencies when a `ModuleNotFoundError` occurs, supporting both pip and pipx environments. Provides compatibility for plugins importing from either `plugins` or `mmrelay.plugins`. Skips files without a `Plugin` class or with unresolved import errors.
 
-    Features:
-    - Automatic dependency installation for missing imports (via pip/pipx)
-    - Compatibility layer for import paths (plugins vs mmrelay.plugins)
-    - Proper sys.path management for plugin directory imports
-    - Comprehensive error handling and logging
+    Parameters:
+        directory (str): Path to the directory containing plugin files.
+        recursive (bool): If True, searches subdirectories recursively.
 
-    Skips files that don't define a Plugin class or have import errors
-    that can't be automatically resolved.
+    Returns:
+        list: Instantiated plugin objects found in the directory.
     """
     plugins = []
     if os.path.isdir(directory):
@@ -626,13 +637,23 @@ def load_plugins_from_directory(directory, recursive=False):
                             )
 
                             # Try to load the module again
-                            spec.loader.exec_module(plugin_module)
-
-                            if hasattr(plugin_module, "Plugin"):
-                                plugins.append(plugin_module.Plugin())
-                            else:
-                                logger.warning(
-                                    f"{plugin_path} does not define a Plugin class."
+                            try:
+                                spec.loader.exec_module(plugin_module)
+
+                                if hasattr(plugin_module, "Plugin"):
+                                    plugins.append(plugin_module.Plugin())
+                                else:
+                                    logger.warning(
+                                        f"{plugin_path} does not define a Plugin class."
+                                    )
+                            except ModuleNotFoundError:
+                                logger.error(
+                                    f"Module {missing_module} still not available after installation. "
+                                    f"The package name might be different from the import name."
+                                )
+                            except Exception as retry_error:
+                                logger.error(
+                                    f"Error loading plugin {plugin_path} after dependency installation: {retry_error}"
                                 )
 
                         except subprocess.CalledProcessError:
@@ -660,25 +681,23 @@ def load_plugins_from_directory(directory, recursive=False):
 
 
 def load_plugins(passed_config=None):
-    """Load and initialize all active plugins based on configuration.
+    """
+    Discovers, loads, and initializes all active plugins based on the provided or global configuration.
 
-    Args:
-        passed_config (dict, optional): Configuration dictionary to use.
-                                       If None, uses global config variable.
+    This function orchestrates the full plugin lifecycle, including:
+    - Loading core, custom, and community plugins as specified in the configuration.
+    - Cloning or updating community plugin repositories and installing their dependencies.
+    - Dynamically loading plugin classes from discovered directories.
+    - Filtering and sorting plugins by their configured priority.
+    - Starting each active plugin.
+
+    If plugins have already been loaded, returns the cached sorted list.
+
+    Parameters:
+        passed_config (dict, optional): Configuration dictionary to use instead of the global configuration.
 
     Returns:
-        list: List of active plugin instances sorted by priority
-
-    This is the main plugin loading function that:
-    - Loads core plugins from mmrelay.plugins package
-    - Processes custom plugins from ~/.mmrelay/plugins/custom and plugins/custom
-    - Downloads and loads community plugins from configured Git repositories
-    - Filters plugins based on active status in configuration
-    - Sorts active plugins by priority and calls their start() method
-    - Sets up proper plugin configuration and channel mapping
-
-    Only plugins explicitly marked as active=true in config are loaded.
-    Custom and community plugins are cloned/updated automatically.
+        list: Active plugin instances, sorted by priority.
     """
     global sorted_active_plugins
     global plugins_loaded
@@ -750,11 +769,15 @@ def load_plugins(passed_config=None):
             plugin_path = os.path.join(custom_dir, plugin_name)
             if os.path.exists(plugin_path):
                 logger.debug(f"Loading custom plugin from: {plugin_path}")
-                plugins.extend(
-                    load_plugins_from_directory(plugin_path, recursive=False)
-                )
-                plugin_found = True
-                break
+                try:
+                    plugins.extend(
+                        load_plugins_from_directory(plugin_path, recursive=False)
+                    )
+                    plugin_found = True
+                    break
+                except Exception as e:
+                    logger.error(f"Failed to load custom plugin {plugin_name}: {e}")
+                    continue
 
         if not plugin_found:
             logger.warning(
@@ -780,7 +803,12 @@ def load_plugins(passed_config=None):
     if active_community_plugins:
         # Ensure all community plugin directories exist
         for dir_path in community_plugin_dirs:
-            os.makedirs(dir_path, exist_ok=True)
+            try:
+                os.makedirs(dir_path, exist_ok=True)
+            except (OSError, PermissionError) as e:
+                logger.warning(
+                    f"Cannot create community plugin directory {dir_path}: {e}"
+                )
 
         logger.debug(
             f"Loading active community plugins: {', '.join(active_community_plugins)}"
@@ -842,11 +870,17 @@ def load_plugins(passed_config=None):
                 plugin_path = os.path.join(dir_path, repo_name)
                 if os.path.exists(plugin_path):
                     logger.info(f"Loading community plugin from: {plugin_path}")
-                    plugins.extend(
-                        load_plugins_from_directory(plugin_path, recursive=True)
-                    )
-                    plugin_found = True
-                    break
+                    try:
+                        plugins.extend(
+                            load_plugins_from_directory(plugin_path, recursive=True)
+                        )
+                        plugin_found = True
+                        break
+                    except Exception as e:
+                        logger.error(
+                            f"Failed to load community plugin {repo_name}: {e}"
+                        )
+                        continue
 
             if not plugin_found:
                 logger.warning(
@@ -900,4 +934,5 @@ def load_plugins(passed_config=None):
     else:
         logger.info("Loaded: none")
 
-    plugins_loaded = True  # Set the flag to indicate that plugins have been load
+    plugins_loaded = True  # Set the flag to indicate that plugins have been loaded
+    return sorted_active_plugins

mmrelay/plugins/base_plugin.py

@@ -7,6 +7,11 @@ import markdown
 import schedule
 
 from mmrelay.config import get_plugin_data_dir
+from mmrelay.constants.database import (
+    DEFAULT_MAX_DATA_ROWS_PER_NODE_BASE,
+    DEFAULT_TEXT_TRUNCATION_LENGTH,
+)
+from mmrelay.constants.queue import DEFAULT_MESSAGE_DELAY
 from mmrelay.db_utils import (
     delete_plugin_data,
     get_plugin_data,
@@ -14,7 +19,7 @@ from mmrelay.db_utils import (
     store_plugin_data,
 )
 from mmrelay.log_utils import get_logger
-from mmrelay.message_queue import DEFAULT_MESSAGE_DELAY, queue_message
+from mmrelay.message_queue import queue_message
 
 # Global config variable that will be set from main.py
 config = None
@@ -47,7 +52,7 @@ class BasePlugin(ABC):
 
     # Class-level default attributes
     plugin_name = None  # Must be overridden in subclasses
-    max_data_rows_per_node = 100
+    max_data_rows_per_node = DEFAULT_MAX_DATA_ROWS_PER_NODE_BASE
     priority = 10
 
     @property
@@ -109,10 +114,22 @@ class BasePlugin(ABC):
                     break
 
             # Get the list of mapped channels
-            self.mapped_channels = [
-                room.get("meshtastic_channel")
-                for room in config.get("matrix_rooms", [])
-            ]
+            # Handle both list format and dict format for matrix_rooms
+            matrix_rooms = config.get("matrix_rooms", [])
+            if isinstance(matrix_rooms, dict):
+                # Dict format: {"room_name": {"id": "...", "meshtastic_channel": 0}}
+                self.mapped_channels = [
+                    room_config.get("meshtastic_channel")
+                    for room_config in matrix_rooms.values()
+                    if isinstance(room_config, dict)
+                ]
+            else:
+                # List format: [{"id": "...", "meshtastic_channel": 0}]
+                self.mapped_channels = [
+                    room.get("meshtastic_channel")
+                    for room in matrix_rooms
+                    if isinstance(room, dict)
+                ]
         else:
             self.mapped_channels = []
 
@@ -251,19 +268,63 @@ class BasePlugin(ABC):
         """
         return self.response_delay
 
+    def get_my_node_id(self):
+        """Get the relay's Meshtastic node ID.
+
+        Returns:
+            int: The relay's node ID, or None if unavailable
+
+        This method provides access to the relay's own node ID without requiring
+        plugins to call connect_meshtastic() directly. Useful for determining
+        if messages are direct messages or for other node identification needs.
+
+        The node ID is cached after first successful retrieval to avoid repeated
+        connection calls, as the relay's node ID is static during runtime.
+        """
+        if hasattr(self, "_my_node_id"):
+            return self._my_node_id
+
+        from mmrelay.meshtastic_utils import connect_meshtastic
+
+        meshtastic_client = connect_meshtastic()
+        if meshtastic_client and meshtastic_client.myInfo:
+            self._my_node_id = meshtastic_client.myInfo.my_node_num
+            return self._my_node_id
+        return None
+
+    def is_direct_message(self, packet):
+        """Check if a Meshtastic packet is a direct message to this relay.
+
+        Args:
+            packet (dict): Meshtastic packet data
+
+        Returns:
+            bool: True if the packet is a direct message to this relay, False otherwise
+
+        This method encapsulates the common pattern of checking if a message
+        is addressed directly to the relay node, eliminating the need for plugins
+        to call connect_meshtastic() directly for DM detection.
+        """
+        toId = packet.get("to")
+        if toId is None:
+            return False
+
+        myId = self.get_my_node_id()
+        return toId == myId
+
     def send_message(self, text: str, channel: int = 0, destination_id=None) -> bool:
         """
-        Send a message to the Meshtastic network via the message queue.
+        Send a message to the Meshtastic network using the message queue.
 
-        Automatically queues the message for broadcast or direct delivery, applying rate limiting as configured. Returns True if the message was successfully queued, or False if the Meshtastic client is unavailable.
+        Queues the specified text for broadcast or direct delivery on the given channel. Returns True if the message was successfully queued, or False if the Meshtastic client is unavailable.
 
         Parameters:
-            text (str): The message text to send.
-            channel (int, optional): Channel index to send the message on. Defaults to 0.
-            destination_id (optional): Destination node ID for direct messages; if None, the message is broadcast.
+            text (str): The message content to send.
+            channel (int, optional): The channel index for sending the message. Defaults to 0.
+            destination_id (optional): The destination node ID for direct messages. If None, the message is broadcast.
 
         Returns:
-            bool: True if the message was queued successfully, False otherwise.
+            bool: True if the message was queued successfully; False otherwise.
         """
         from mmrelay.meshtastic_utils import connect_meshtastic
 
@@ -272,9 +333,7 @@ class BasePlugin(ABC):
             self.logger.error("No Meshtastic client available")
             return False
 
-        description = (
-            f"Plugin {self.plugin_name}: {text[:50]}{'...' if len(text) > 50 else ''}"
-        )
+        description = f"Plugin {self.plugin_name}: {text[:DEFAULT_TEXT_TRUNCATION_LENGTH]}{'...' if len(text) > DEFAULT_TEXT_TRUNCATION_LENGTH else ''}"
 
         send_kwargs = {
             "text": text,

mmrelay/plugins/drop_plugin.py

@@ -2,6 +2,8 @@ import re
 
 from haversine import haversine
 
+from mmrelay.constants.database import DEFAULT_DISTANCE_KM_FALLBACK, DEFAULT_RADIUS_KM
+from mmrelay.constants.formats import TEXT_MESSAGE_APP
 from mmrelay.meshtastic_utils import connect_meshtastic
 from mmrelay.plugins.base_plugin import BasePlugin
 
@@ -25,6 +27,14 @@ class Plugin(BasePlugin):
     async def handle_meshtastic_message(
         self, packet, formatted_message, longname, meshnet_name
     ):
+        """
+        Handles incoming Meshtastic packets for the drop message plugin, delivering or storing dropped messages based on packet content and node location.
+
+        When a packet is received, attempts to deliver any stored dropped messages to the sender if they are within a configured radius of the message's location and are not the original dropper. If the packet contains a properly formatted drop command, extracts the message and stores it with the sender's current location for future delivery.
+
+        Returns:
+            True if a drop command was processed and stored, False otherwise.
+        """
         meshtastic_client = connect_meshtastic()
         nodeInfo = meshtastic_client.getMyNodeInfo()
 
@@ -55,10 +65,8 @@ class Plugin(BasePlugin):
                             message["location"],
                         )
                     except (ValueError, TypeError):
-                        distance_km = 1000
-                    radius_km = (
-                        self.config["radius_km"] if "radius_km" in self.config else 5
-                    )
+                        distance_km = DEFAULT_DISTANCE_KM_FALLBACK
+                    radius_km = self.config.get("radius_km", DEFAULT_RADIUS_KM)
                     if distance_km <= radius_km:
                         target_node = packet["fromId"]
                         self.logger.debug(f"Sending dropped message to {target_node}")
@@ -76,7 +84,7 @@ class Plugin(BasePlugin):
         if (
             "decoded" in packet
             and "portnum" in packet["decoded"]
-            and packet["decoded"]["portnum"] == "TEXT_MESSAGE_APP"
+            and packet["decoded"]["portnum"] == TEXT_MESSAGE_APP
         ):
             text = packet["decoded"]["text"] if "text" in packet["decoded"] else None
             if f"!{self.plugin_name}" not in text:

mmrelay/plugins/mesh_relay_plugin.py

@@ -6,6 +6,7 @@ import re
 
 from meshtastic import mesh_pb2
 
+from mmrelay.constants.database import DEFAULT_MAX_DATA_ROWS_PER_NODE_MESH_RELAY
 from mmrelay.plugins.base_plugin import BasePlugin, config
 
 
@@ -25,21 +26,17 @@ class Plugin(BasePlugin):
     """
 
     plugin_name = "mesh_relay"
-    max_data_rows_per_node = 50
+    max_data_rows_per_node = DEFAULT_MAX_DATA_ROWS_PER_NODE_MESH_RELAY
 
     def normalize(self, dict_obj):
-        """Normalize packet data to consistent dictionary format.
+        """
+        Converts packet data in various formats (dict, JSON string, or plain string) into a normalized dictionary with raw data fields removed.
 
-        Args:
-            dict_obj: Packet data (dict, JSON string, or plain string)
+        Parameters:
+            dict_obj: Packet data as a dictionary, JSON string, or plain string.
 
         Returns:
-            dict: Normalized packet dictionary with raw data stripped
-
-        Handles various packet formats:
-        - Dict objects (passed through)
-        - JSON strings (parsed)
-        - Plain strings (wrapped in TEXT_MESSAGE_APP format)
+            A dictionary representing the normalized packet with raw fields stripped.
         """
         if not isinstance(dict_obj, dict):
             try: