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

mmrelay/message_queue.py

@@ -0,0 +1,475 @@
+"""
+Message queue system for MMRelay.
+
+Provides transparent message queuing with rate limiting to prevent overwhelming
+the Meshtastic network. Messages are queued in memory and sent at the configured
+rate, respecting connection state and firmware constraints.
+"""
+
+import asyncio
+import threading
+import time
+from dataclasses import dataclass
+from queue import Empty, Queue
+from typing import Callable, Optional
+
+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:
+    """Represents a message in the queue with metadata."""
+
+    timestamp: float
+    send_function: Callable
+    args: tuple
+    kwargs: dict
+    description: str
+    # Optional message mapping information for replies/reactions
+    mapping_info: Optional[dict] = None
+
+
+class MessageQueue:
+    """
+    Simple FIFO message queue with rate limiting for Meshtastic messages.
+
+    Queues messages in memory and sends them in order at the configured rate to prevent
+    overwhelming the mesh network. Respects connection state and automatically
+    pauses during reconnections.
+    """
+
+    def __init__(self):
+        """
+        Initialize the MessageQueue with an empty queue, state variables, and a thread lock for safe operation.
+        """
+        self._queue = Queue()
+        self._processor_task = None
+        self._running = False
+        self._lock = threading.Lock()
+        self._last_send_time = 0.0
+        self._message_delay = DEFAULT_MESSAGE_DELAY
+
+    def start(self, message_delay: float = DEFAULT_MESSAGE_DELAY):
+        """
+        Starts the message queue processor with the 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.
+        """
+        with self._lock:
+            if self._running:
+                return
+
+            # Validate and enforce firmware minimum
+            if message_delay < 2.0:
+                logger.warning(
+                    f"Message delay {message_delay}s below firmware minimum (2.0s), using 2.0s"
+                )
+                self._message_delay = 2.0
+            else:
+                self._message_delay = message_delay
+            self._running = True
+
+            # Start the processor in the event loop
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    self._processor_task = loop.create_task(self._process_queue())
+                    logger.info(
+                        f"Message queue started with {self._message_delay}s message delay"
+                    )
+                else:
+                    # Event loop exists but not running yet, defer startup
+                    logger.debug(
+                        "Event loop not running yet, will start processor later"
+                    )
+            except RuntimeError:
+                # No event loop running, will start when one is available
+                logger.debug(
+                    "No event loop available, queue processor will start later"
+                )
+
+    def stop(self):
+        """
+        Stops the message queue processor and cancels the processing task if active.
+        """
+        with self._lock:
+            if not self._running:
+                return
+
+            self._running = False
+
+            if self._processor_task:
+                self._processor_task.cancel()
+                self._processor_task = None
+
+            logger.info("Message queue stopped")
+
+    def enqueue(
+        self,
+        send_function: Callable,
+        *args,
+        description: str = "",
+        mapping_info: dict = None,
+        **kwargs,
+    ) -> bool:
+        """
+        Adds a message to the queue for rate-limited, ordered sending.
+
+        Parameters:
+            send_function (Callable): The function to call to send the message.
+            *args: Positional arguments for the send function.
+            description (str, optional): Human-readable description for logging purposes.
+            mapping_info (dict, optional): Optional metadata for message mapping (e.g., replies or reactions).
+            **kwargs: Keyword arguments for the send function.
+
+        Returns:
+            bool: True if the message was successfully enqueued; False if the queue is not running or is full.
+        """
+        # Ensure processor is started if event loop is now available.
+        # This is called outside the lock to prevent potential deadlocks.
+        self.ensure_processor_started()
+
+        with self._lock:
+            if not self._running:
+                # Refuse to send to prevent blocking the event loop
+                logger.error(f"Queue not running, cannot send message: {description}")
+                logger.error(
+                    "Application is in invalid state - message queue should be started before sending messages"
+                )
+                return False
+
+            # Check queue size to prevent memory issues
+            if self._queue.qsize() >= MAX_QUEUE_SIZE:
+                logger.warning(
+                    f"Message queue full ({self._queue.qsize()}/{MAX_QUEUE_SIZE}), dropping message: {description}"
+                )
+                return False
+
+            message = QueuedMessage(
+                timestamp=time.time(),
+                send_function=send_function,
+                args=args,
+                kwargs=kwargs,
+                description=description,
+                mapping_info=mapping_info,
+            )
+
+            self._queue.put(message)
+            # Only log queue status when there are multiple messages
+            queue_size = self._queue.qsize()
+            if queue_size >= 2:
+                logger.debug(
+                    f"Queued message ({queue_size}/{MAX_QUEUE_SIZE}): {description}"
+                )
+            return True
+
+    def get_queue_size(self) -> int:
+        """
+        Return the number of messages currently in the queue.
+
+        Returns:
+            int: The current queue size.
+        """
+        return self._queue.qsize()
+
+    def is_running(self) -> bool:
+        """
+        Return whether the message queue processor is currently active.
+        """
+        return self._running
+
+    def get_status(self) -> dict:
+        """
+        Return a dictionary with the current status of the message queue, including running state, queue size, message delay, processor activity, last send time, and time since last send.
+
+        Returns:
+            dict: Status information about the message queue for debugging and monitoring.
+        """
+        return {
+            "running": self._running,
+            "queue_size": self._queue.qsize(),
+            "message_delay": self._message_delay,
+            "processor_task_active": self._processor_task is not None
+            and not self._processor_task.done(),
+            "last_send_time": self._last_send_time,
+            "time_since_last_send": (
+                time.time() - self._last_send_time if self._last_send_time > 0 else None
+            ),
+        }
+
+    def ensure_processor_started(self):
+        """
+        Start the queue processor task if the queue is running and no processor task exists.
+
+        This method checks if the queue is active and, if so, attempts to create and start the asynchronous processor task within the current event loop.
+        """
+        with self._lock:
+            if self._running and self._processor_task is None:
+                try:
+                    loop = asyncio.get_event_loop()
+                    if loop.is_running():
+                        self._processor_task = loop.create_task(self._process_queue())
+                        logger.info(
+                            f"Message queue processor started with {self._message_delay}s message delay"
+                        )
+                except RuntimeError:
+                    # Still no event loop available
+                    pass
+
+    async def _process_queue(self):
+        """
+        Asynchronously processes messages from the queue, sending each in order while enforcing rate limiting and connection readiness.
+
+        This method runs as a background task, monitoring the queue, waiting for the connection to be ready, and ensuring a minimum delay between sends. Messages are sent using their provided callable, and optional message mapping is handled after successful sends. The processor logs queue depth warnings, handles errors gracefully, and maintains FIFO order even when waiting for connection or rate limits.
+        """
+        logger.debug("Message queue processor started")
+        current_message = None
+
+        while self._running:
+            try:
+                # Get next message if we don't have one waiting
+                if current_message is None:
+                    # Monitor queue depth for operational awareness
+                    queue_size = self._queue.qsize()
+                    if queue_size > QUEUE_HIGH_WATER_MARK:
+                        logger.warning(
+                            f"Queue depth high: {queue_size} messages pending"
+                        )
+                    elif queue_size > QUEUE_MEDIUM_WATER_MARK:
+                        logger.info(
+                            f"Queue depth moderate: {queue_size} messages pending"
+                        )
+
+                    # Get next message (non-blocking)
+                    try:
+                        current_message = self._queue.get_nowait()
+                    except Empty:
+                        # No messages, wait a bit and continue
+                        await asyncio.sleep(0.1)
+                        continue
+
+                # Check if we should send (connection state, etc.)
+                if not self._should_send_message():
+                    # Keep the message and wait - don't requeue to maintain FIFO order
+                    logger.debug(
+                        f"Connection not ready, waiting to send: {current_message.description}"
+                    )
+                    await asyncio.sleep(1.0)
+                    continue
+
+                # Check if we need to wait for message delay (only if we've sent before)
+                if self._last_send_time > 0:
+                    time_since_last = time.time() - self._last_send_time
+                    if time_since_last < self._message_delay:
+                        wait_time = self._message_delay - time_since_last
+                        logger.debug(
+                            f"Rate limiting: waiting {wait_time:.1f}s before sending"
+                        )
+                        await asyncio.sleep(wait_time)
+                        continue
+
+                # Send the message
+                try:
+                    logger.debug(
+                        f"Sending queued message: {current_message.description}"
+                    )
+                    # Run synchronous Meshtastic I/O operations in executor to prevent blocking event loop
+                    # Use lambda with default arguments to properly capture loop variables
+                    result = await asyncio.get_running_loop().run_in_executor(
+                        None,
+                        lambda msg=current_message: msg.send_function(
+                            *msg.args, **msg.kwargs
+                        ),
+                    )
+
+                    # Update last send time
+                    self._last_send_time = time.time()
+
+                    if result is None:
+                        logger.warning(
+                            f"Message send returned None: {current_message.description}"
+                        )
+                    else:
+                        logger.debug(
+                            f"Successfully sent queued message: {current_message.description}"
+                        )
+
+                        # Handle message mapping if provided
+                        if current_message.mapping_info and hasattr(result, "id"):
+                            self._handle_message_mapping(
+                                result, current_message.mapping_info
+                            )
+
+                except Exception as e:
+                    logger.error(
+                        f"Error sending queued message '{current_message.description}': {e}"
+                    )
+
+                # Mark task as done and clear current message
+                self._queue.task_done()
+                current_message = None
+
+            except asyncio.CancelledError:
+                logger.debug("Message queue processor cancelled")
+                if current_message:
+                    logger.warning(
+                        f"Message in flight was dropped during shutdown: {current_message.description}"
+                    )
+                break
+            except Exception as e:
+                logger.error(f"Error in message queue processor: {e}")
+                await asyncio.sleep(1.0)  # Prevent tight error loop
+
+    def _should_send_message(self) -> bool:
+        """
+        Determine whether it is currently safe to send a message based on Meshtastic client connection and reconnection state.
+
+        Returns:
+            bool: True if the client is connected and not reconnecting; False otherwise.
+        """
+        # Import here to avoid circular imports
+        try:
+            from mmrelay.meshtastic_utils import meshtastic_client, reconnecting
+
+            # Don't send during reconnection
+            if reconnecting:
+                logger.debug("Not sending - reconnecting is True")
+                return False
+
+            # Don't send if no client
+            if meshtastic_client is None:
+                logger.debug("Not sending - meshtastic_client is None")
+                return False
+
+            # Check if client is connected
+            if hasattr(meshtastic_client, "is_connected"):
+                is_conn = meshtastic_client.is_connected
+                if not (is_conn() if callable(is_conn) else is_conn):
+                    logger.debug("Not sending - client not connected")
+                    return False
+
+            logger.debug("Connection check passed - ready to send")
+            return True
+
+        except ImportError as e:
+            # ImportError indicates a serious problem with application structure,
+            # often during shutdown as modules are unloaded.
+            logger.critical(
+                f"Cannot import meshtastic_utils - serious application error: {e}. Stopping message queue."
+            )
+            self.stop()
+            return False
+
+    def _handle_message_mapping(self, result, mapping_info):
+        """
+        Stores and prunes message mapping information after a message is sent.
+
+        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`.
+
+        This method updates the message mapping database with the new mapping and prunes old mappings if configured.
+        """
+        try:
+            # Import here to avoid circular imports
+            from mmrelay.db_utils import prune_message_map, store_message_map
+
+            # Extract mapping information
+            matrix_event_id = mapping_info.get("matrix_event_id")
+            room_id = mapping_info.get("room_id")
+            text = mapping_info.get("text")
+            meshnet = mapping_info.get("meshnet")
+
+            if matrix_event_id and room_id and text:
+                # Store the message mapping
+                store_message_map(
+                    result.id,
+                    matrix_event_id,
+                    room_id,
+                    text,
+                    meshtastic_meshnet=meshnet,
+                )
+                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)
+                if msgs_to_keep > 0:
+                    prune_message_map(msgs_to_keep)
+
+        except Exception as e:
+            logger.error(f"Error handling message mapping: {e}")
+
+
+# Global message queue instance
+_message_queue = MessageQueue()
+
+
+def get_message_queue() -> MessageQueue:
+    """
+    Return the global instance of the message queue used for managing and rate-limiting message sending.
+    """
+    return _message_queue
+
+
+def start_message_queue(message_delay: float = DEFAULT_MESSAGE_DELAY):
+    """
+    Start the global message queue processor with the given minimum delay between messages.
+
+    Parameters:
+        message_delay (float): Minimum number of seconds to wait between sending messages.
+    """
+    _message_queue.start(message_delay)
+
+
+def stop_message_queue():
+    """
+    Stops the global message queue processor, preventing further message processing until restarted.
+    """
+    _message_queue.stop()
+
+
+def queue_message(
+    send_function: Callable,
+    *args,
+    description: str = "",
+    mapping_info: dict = None,
+    **kwargs,
+) -> bool:
+    """
+    Enqueues a message for sending via the global message queue.
+
+    Parameters:
+        send_function (Callable): The function to execute for sending the message.
+        description (str, optional): Human-readable description of the message for logging purposes.
+        mapping_info (dict, optional): Additional metadata for message mapping, such as reply or reaction information.
+
+    Returns:
+        bool: True if the message was successfully enqueued; False if the queue is not running or full.
+    """
+    return _message_queue.enqueue(
+        send_function,
+        *args,
+        description=description,
+        mapping_info=mapping_info,
+        **kwargs,
+    )
+
+
+def get_queue_status() -> dict:
+    """
+    Return detailed status information about the global message queue.
+
+    Returns:
+        dict: A dictionary containing the running state, queue size, message delay, processor task activity, last send time, and time since last send.
+    """
+    return _message_queue.get_status()

mmrelay/plugin_loader.py

@@ -896,8 +896,8 @@ def load_plugins(passed_config=None):
             getattr(plugin, "plugin_name", plugin.__class__.__name__)
             for plugin in sorted_active_plugins
         ]
-        logger.info(f"Plugins loaded: {', '.join(plugin_names)}")
+        logger.info(f"Loaded: {', '.join(plugin_names)}")
     else:
-        logger.info("Plugins loaded: none")
+        logger.info("Loaded: none")
 
     plugins_loaded = True  # Set the flag to indicate that plugins have been load

mmrelay/plugins/base_plugin.py

@@ -14,10 +14,14 @@ 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
 
 # Global config variable that will be set from main.py
 config = None
 
+# Track if we've already shown the deprecated warning
+_deprecated_warning_shown = False
+
 
 class BasePlugin(ABC):
     """Abstract base class for all mmrelay plugins.
@@ -59,20 +63,16 @@ class BasePlugin(ABC):
         return ""
 
     def __init__(self, plugin_name=None) -> None:
-        """Initialize the plugin with configuration and logging.
+        """
+        Initialize the plugin instance, setting its name, logger, configuration, mapped channels, and response delay.
 
-        Args:
-            plugin_name (str, optional): Plugin name override. If not provided,
-                                       uses class-level plugin_name attribute.
+        Parameters:
+            plugin_name (str, optional): Overrides the plugin's name. If not provided, uses the class-level `plugin_name` attribute.
 
         Raises:
-            ValueError: If plugin_name is not set via parameter or class attribute
+            ValueError: If the plugin name is not set via parameter or class attribute.
 
-        Sets up:
-        - Plugin-specific logger
-        - Configuration from global config
-        - Channel mapping and validation
-        - Response delay settings
+        Loads plugin-specific configuration from the global config, validates assigned channels, and determines the response delay, enforcing a minimum of 2.0 seconds. Logs a warning if deprecated configuration options are used or if channels are not mapped.
         """
         # Allow plugin_name to be passed as a parameter for simpler initialization
         # This maintains backward compatibility while providing a cleaner API
@@ -132,26 +132,43 @@ class BasePlugin(ABC):
                 f"Plugin '{self.plugin_name}': Channels {invalid_channels} are not mapped in configuration."
             )
 
-        # Get the response delay from the meshtastic config only
-        self.response_delay = 3  # Default value
+        # Get the response delay from the meshtastic config
+        self.response_delay = DEFAULT_MESSAGE_DELAY
         if config is not None:
-            self.response_delay = config.get("meshtastic", {}).get(
-                "plugin_response_delay", self.response_delay
-            )
+            meshtastic_config = config.get("meshtastic", {})
+
+            # Check for new message_delay option first, with fallback to deprecated option
+            delay = None
+            delay_key = None
+            if "message_delay" in meshtastic_config:
+                delay = meshtastic_config["message_delay"]
+                delay_key = "message_delay"
+            elif "plugin_response_delay" in meshtastic_config:
+                delay = meshtastic_config["plugin_response_delay"]
+                delay_key = "plugin_response_delay"
+                # Show deprecated warning only once globally
+                global _deprecated_warning_shown
+                if not _deprecated_warning_shown:
+                    self.logger.warning(
+                        "Configuration option 'plugin_response_delay' is deprecated. "
+                        "Please use 'message_delay' instead. Support for 'plugin_response_delay' will be removed in a future version."
+                    )
+                    _deprecated_warning_shown = True
+
+            if delay is not None:
+                self.response_delay = delay
+                # Enforce minimum delay of 2 seconds due to firmware constraints
+                if self.response_delay < 2.0:
+                    self.logger.warning(
+                        f"{delay_key} of {self.response_delay}s is below minimum of 2.0s (firmware constraint). Using 2.0s."
+                    )
+                    self.response_delay = 2.0
 
     def start(self):
-        """Start the plugin and set up scheduled tasks if configured.
-
-        Called automatically when the plugin is loaded. Checks plugin configuration
-        for scheduling settings and sets up background jobs accordingly.
-
-        Supported schedule formats in config:
-        - schedule.hours + schedule.at: Run every N hours at specific time
-        - schedule.minutes + schedule.at: Run every N minutes at specific time
-        - schedule.hours: Run every N hours
-        - schedule.minutes: Run every N minutes
+        """
+        Starts the plugin and configures scheduled background tasks based on plugin settings.
 
-        Creates a daemon thread to run the scheduler if any schedule is configured.
+        If scheduling options are present in the plugin configuration, sets up periodic execution of the `background_job` method using the specified schedule. Runs scheduled jobs in a separate daemon thread. If no scheduling is configured, the plugin starts without background tasks.
         """
         if "schedule" not in self.config or (
             "at" not in self.config["schedule"]
@@ -224,28 +241,64 @@ class BasePlugin(ABC):
         return data
 
     def get_response_delay(self):
-        """Get the configured response delay for meshtastic messages.
+        """
+        Return the configured delay in seconds before sending a Meshtastic response.
 
-        Returns:
-            int: Delay in seconds before sending responses (default: 3)
+        The delay is determined by the `meshtastic.message_delay` configuration option, defaulting to 2.2 seconds with a minimum of 2.0 seconds. The deprecated `plugin_response_delay` option is also supported for backward compatibility.
 
-        Used to prevent message flooding and ensure proper radio etiquette.
-        Delay is configured via meshtastic.plugin_response_delay in config.
+        Returns:
+            float: The response delay in seconds.
         """
         return self.response_delay
 
-    def is_channel_enabled(self, channel, is_direct_message=False):
-        """Check if the plugin should respond on a specific channel.
+    def send_message(self, text: str, channel: int = 0, destination_id=None) -> bool:
+        """
+        Send a message to the Meshtastic network via the message queue.
 
-        Args:
-            channel: Channel identifier to check
-            is_direct_message (bool): Whether this is a direct message
+        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.
+
+        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.
 
         Returns:
-            bool: True if plugin should respond, False otherwise
+            bool: True if the message was queued successfully, False otherwise.
+        """
+        from mmrelay.meshtastic_utils import connect_meshtastic
+
+        meshtastic_client = connect_meshtastic()
+        if not meshtastic_client:
+            self.logger.error("No Meshtastic client available")
+            return False
+
+        description = (
+            f"Plugin {self.plugin_name}: {text[:50]}{'...' if len(text) > 50 else ''}"
+        )
+
+        send_kwargs = {
+            "text": text,
+            "channelIndex": channel,
+        }
+        if destination_id:
+            send_kwargs["destinationId"] = destination_id
+
+        return queue_message(
+            meshtastic_client.sendText,
+            description=description,
+            **send_kwargs,
+        )
+
+    def is_channel_enabled(self, channel, is_direct_message=False):
+        """
+        Determine whether the plugin should respond to a message on the specified channel or direct message.
+
+        Parameters:
+            channel: The channel identifier to check.
+            is_direct_message (bool): Set to True if the message is a direct message.
 
-        Direct messages always return True if the plugin is active.
-        For channel messages, checks if channel is in plugin's configured channels list.
+        Returns:
+            bool: True if the plugin should respond on the given channel or to a direct message; False otherwise.
         """
         if is_direct_message:
             return True  # Always respond to DMs if the plugin is active