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

mmrelay/meshtastic_utils.py

@@ -340,7 +340,7 @@ async def reconnect():
 
 def on_meshtastic_message(packet, interface):
     """
-    Process incoming Meshtastic messages and relay them to Matrix rooms or plugins according to message type and configuration.
+    Processes incoming Meshtastic messages and relays them to Matrix rooms or plugins based on message type and configuration.
 
     Handles reactions and replies by relaying them to Matrix if enabled. Normal text messages are relayed to all mapped Matrix rooms unless handled by a plugin or directed to the relay node. Non-text messages are passed to plugins for processing. Messages from unmapped channels or disabled detection sensors are ignored. Ensures sender information is retrieved or stored as needed.
     """
@@ -432,11 +432,16 @@ def on_meshtastic_message(packet, interface):
                 else meshtastic_text
             )
 
-            # Ensure that meshnet_name is always included, using our own meshnet for accuracy.
-            full_display_name = f"{longname}/{meshnet_name}"
+            # Import the matrix prefix function
+            from mmrelay.matrix_utils import get_matrix_prefix
+
+            # Get the formatted prefix for the reaction
+            prefix = get_matrix_prefix(config, longname, shortname, meshnet_name)
 
             reaction_symbol = text.strip() if (text and text.strip()) else "⚠️"
-            reaction_message = f'\n [{full_display_name}] reacted {reaction_symbol} to "{abbreviated_text}"'
+            reaction_message = (
+                f'\n {prefix}reacted {reaction_symbol} to "{abbreviated_text}"'
+            )
 
             # Relay the reaction as emote to Matrix, preserving the original meshnet name
             asyncio.run_coroutine_threadsafe(
@@ -469,9 +474,12 @@ def on_meshtastic_message(packet, interface):
             # orig = (matrix_event_id, matrix_room_id, meshtastic_text, meshtastic_meshnet)
             matrix_event_id, matrix_room_id, meshtastic_text, meshtastic_meshnet = orig
 
-            # Format the reply message for Matrix
-            full_display_name = f"{longname}/{meshnet_name}"
-            formatted_message = f"[{full_display_name}]: {text}"
+            # Import the matrix prefix function
+            from mmrelay.matrix_utils import get_matrix_prefix
+
+            # Get the formatted prefix for the reply
+            prefix = get_matrix_prefix(config, longname, shortname, meshnet_name)
+            formatted_message = f"{prefix}{text}"
 
             logger.info(f"Relaying Meshtastic reply from {longname} to Matrix")
 
@@ -562,7 +570,12 @@ def on_meshtastic_message(packet, interface):
         if not shortname:
             shortname = str(sender)
 
-        formatted_message = f"[{longname}/{meshnet_name}]: {text}"
+        # Import the matrix prefix function
+        from mmrelay.matrix_utils import get_matrix_prefix
+
+        # Get the formatted prefix
+        prefix = get_matrix_prefix(config, longname, shortname, meshnet_name)
+        formatted_message = f"{prefix}{text}"
 
         # Plugin functionality - Check if any plugin handles this message before relaying
         from mmrelay.plugin_loader import load_plugins

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