mmrelay 1.2.6__py3-none-any.whl

mmrelay/constants/__init__.py

@@ -0,0 +1,65 @@
+"""
+Constants package for MMRelay.
+
+This package organizes all application constants by functional area:
+- app: Application metadata and version information
+- queue: Message queue configuration constants
+- network: Network connection and timeout constants
+- formats: Message format templates and prefixes
+- messages: User-facing strings and templates
+- database: Database-related constants
+- config: Configuration section and key constants
+- plugins: Plugin system security and validation constants
+
+Usage:
+    from mmrelay.constants import queue
+    from mmrelay.constants.app import APP_NAME
+    from mmrelay.constants.queue import DEFAULT_MESSAGE_DELAY
+    from mmrelay.constants.plugins import DEFAULT_ALLOWED_COMMUNITY_HOSTS
+"""
+
+# Re-export commonly used constants for convenience
+from .app import APP_AUTHOR, APP_NAME
+from .config import (
+    CONFIG_KEY_LEVEL,
+    CONFIG_SECTION_LOGGING,
+    CONFIG_SECTION_MATRIX,
+    CONFIG_SECTION_MESHTASTIC,
+    DEFAULT_LOG_LEVEL,
+)
+from .formats import DEFAULT_MATRIX_PREFIX, DEFAULT_MESHTASTIC_PREFIX
+from .plugins import (
+    DEFAULT_ALLOWED_COMMUNITY_HOSTS,
+    PIP_SOURCE_FLAGS,
+    RISKY_REQUIREMENT_PREFIXES,
+)
+from .queue import (
+    DEFAULT_MESSAGE_DELAY,
+    MAX_QUEUE_SIZE,
+    QUEUE_HIGH_WATER_MARK,
+    QUEUE_MEDIUM_WATER_MARK,
+)
+
+__all__ = [
+    # App constants
+    "APP_NAME",
+    "APP_AUTHOR",
+    # Config constants
+    "CONFIG_SECTION_MATRIX",
+    "CONFIG_SECTION_MESHTASTIC",
+    "CONFIG_SECTION_LOGGING",
+    "CONFIG_KEY_LEVEL",
+    "DEFAULT_LOG_LEVEL",
+    # Queue constants
+    "DEFAULT_MESSAGE_DELAY",
+    "MAX_QUEUE_SIZE",
+    "QUEUE_HIGH_WATER_MARK",
+    "QUEUE_MEDIUM_WATER_MARK",
+    # Format constants
+    "DEFAULT_MESHTASTIC_PREFIX",
+    "DEFAULT_MATRIX_PREFIX",
+    # Plugin constants
+    "DEFAULT_ALLOWED_COMMUNITY_HOSTS",
+    "PIP_SOURCE_FLAGS",
+    "RISKY_REQUIREMENT_PREFIXES",
+]

mmrelay/constants/app.py

@@ -0,0 +1,29 @@
+"""
+Application metadata constants.
+
+Contains version information, application name, and other metadata
+used throughout the MMRelay application.
+"""
+
+# Application identification
+APP_NAME = "mmrelay"
+APP_AUTHOR = None  # No author directory for platformdirs
+
+# Application display names
+APP_DISPLAY_NAME = "MMRelay"
+APP_FULL_NAME = "MMRelay - Meshtastic <=> Matrix Relay"
+
+# Matrix client identification
+MATRIX_DEVICE_NAME = "MMRelay"
+
+# Platform-specific constants
+WINDOWS_PLATFORM = "win32"
+
+# Package and installation constants
+PACKAGE_NAME_E2E = "mmrelay[e2e]"
+PYTHON_OLM_PACKAGE = "python-olm"
+
+# Configuration file names
+CREDENTIALS_FILENAME = "credentials.json"
+CONFIG_FILENAME = "config.yaml"
+STORE_DIRNAME = "store"

mmrelay/constants/config.py

@@ -0,0 +1,78 @@
+"""
+Configuration section and key constants.
+
+Contains configuration section names, key names, and default values
+used throughout the configuration system.
+"""
+
+# Configuration section names
+CONFIG_SECTION_MATRIX = "matrix"
+CONFIG_SECTION_MATRIX_ROOMS = "matrix_rooms"
+CONFIG_SECTION_MESHTASTIC = "meshtastic"
+CONFIG_SECTION_LOGGING = "logging"
+CONFIG_SECTION_DATABASE = "database"
+CONFIG_SECTION_PLUGINS = "plugins"
+CONFIG_SECTION_COMMUNITY_PLUGINS = "community-plugins"
+CONFIG_SECTION_CUSTOM_PLUGINS = "custom-plugins"
+
+# Matrix configuration keys
+CONFIG_KEY_HOMESERVER = "homeserver"
+CONFIG_KEY_ACCESS_TOKEN = (
+    "access_token"  # nosec B105 - This is a config key name, not a hardcoded password
+)
+CONFIG_KEY_BOT_USER_ID = "bot_user_id"
+CONFIG_KEY_PREFIX_ENABLED = "prefix_enabled"
+CONFIG_KEY_PREFIX_FORMAT = "prefix_format"
+
+# Matrix rooms configuration keys
+CONFIG_KEY_ID = "id"
+CONFIG_KEY_MESHTASTIC_CHANNEL = "meshtastic_channel"
+
+# Meshtastic configuration keys (additional to network.py)
+CONFIG_KEY_MESHNET_NAME = "meshnet_name"
+CONFIG_KEY_MESSAGE_INTERACTIONS = "message_interactions"
+CONFIG_KEY_REACTIONS = "reactions"
+CONFIG_KEY_REPLIES = "replies"
+CONFIG_KEY_BROADCAST_ENABLED = "broadcast_enabled"
+CONFIG_KEY_DETECTION_SENSOR = "detection_sensor"
+CONFIG_KEY_MESSAGE_DELAY = "message_delay"
+CONFIG_KEY_HEALTH_CHECK = "health_check"
+CONFIG_KEY_ENABLED = "enabled"
+CONFIG_KEY_HEARTBEAT_INTERVAL = "heartbeat_interval"
+
+# Logging configuration keys
+CONFIG_KEY_LEVEL = "level"
+CONFIG_KEY_LOG_TO_FILE = "log_to_file"
+CONFIG_KEY_FILENAME = "filename"
+CONFIG_KEY_MAX_LOG_SIZE = "max_log_size"
+CONFIG_KEY_BACKUP_COUNT = "backup_count"
+CONFIG_KEY_COLOR_ENABLED = "color_enabled"
+CONFIG_KEY_DEBUG = "debug"
+
+# Database configuration keys
+CONFIG_KEY_PATH = "path"
+CONFIG_KEY_MSG_MAP = "msg_map"
+CONFIG_KEY_MSGS_TO_KEEP = "msgs_to_keep"
+CONFIG_KEY_WIPE_ON_RESTART = "wipe_on_restart"
+
+# Plugin configuration keys
+CONFIG_KEY_ACTIVE = "active"
+CONFIG_KEY_CHANNELS = "channels"
+CONFIG_KEY_UNITS = "units"
+CONFIG_KEY_REPOSITORY = "repository"
+CONFIG_KEY_TAG = "tag"
+
+# Default configuration values
+DEFAULT_LOG_LEVEL = "info"
+DEFAULT_WEATHER_UNITS = "metric"
+DEFAULT_WEATHER_UNITS_IMPERIAL = "imperial"
+DEFAULT_PREFIX_ENABLED = True
+DEFAULT_BROADCAST_ENABLED = True
+DEFAULT_DETECTION_SENSOR = True
+DEFAULT_HEALTH_CHECK_ENABLED = True
+DEFAULT_HEARTBEAT_INTERVAL = 60
+DEFAULT_COLOR_ENABLED = True
+DEFAULT_WIPE_ON_RESTART = False
+
+# E2EE constants
+E2EE_KEY_SHARING_DELAY_SECONDS = 5

mmrelay/constants/database.py

@@ -0,0 +1,22 @@
+"""
+Database-related constants.
+
+Contains default values for database configuration, message retention,
+and data management settings.
+"""
+
+# Message retention defaults
+DEFAULT_MSGS_TO_KEEP = 500
+DEFAULT_MAX_DATA_ROWS_PER_NODE_BASE = 100  # Base plugin default
+DEFAULT_MAX_DATA_ROWS_PER_NODE_MESH_RELAY = 50  # Reduced for mesh relay performance
+
+# Progress tracking
+PROGRESS_TOTAL_STEPS = 100
+PROGRESS_COMPLETE = 100
+
+# Text truncation
+DEFAULT_TEXT_TRUNCATION_LENGTH = 50
+
+# Distance calculations
+DEFAULT_DISTANCE_KM_FALLBACK = 1000  # Fallback distance when calculation fails
+DEFAULT_RADIUS_KM = 5  # Default radius for location-based filtering

mmrelay/constants/formats.py

@@ -0,0 +1,20 @@
+"""
+Message format constants.
+
+Contains default message prefixes, format templates, and other
+formatting-related constants used for message display and relay.
+"""
+
+# Default message prefix formats
+DEFAULT_MESHTASTIC_PREFIX = "{display5}[M]: "
+DEFAULT_MATRIX_PREFIX = "[{long}/{mesh}]: "
+
+# Port number constants for message types
+TEXT_MESSAGE_APP = "TEXT_MESSAGE_APP"
+DETECTION_SENSOR_APP = "DETECTION_SENSOR_APP"
+
+# Emoji flag value
+EMOJI_FLAG_VALUE = 1
+
+# Default channel
+DEFAULT_CHANNEL = 0

mmrelay/constants/messages.py

@@ -0,0 +1,45 @@
+"""
+User-facing messages and string templates.
+
+Contains error messages, log templates, command responses, and other
+strings that are displayed to users or logged.
+"""
+
+# Log configuration defaults
+DEFAULT_LOG_SIZE_MB = 5
+DEFAULT_LOG_BACKUP_COUNT = 1
+LOG_SIZE_BYTES_MULTIPLIER = 1024 * 1024  # Convert MB to bytes
+
+# Numeric constants for comparisons
+PORTNUM_NUMERIC_VALUE = 1  # Numeric equivalent of TEXT_MESSAGE_APP
+DEFAULT_CHANNEL_VALUE = 0
+
+# Message formatting constants
+MAX_TRUNCATION_LENGTH = 20  # Maximum characters for variable truncation
+TRUNCATION_LOG_LIMIT = 6  # Only log first N truncations to avoid spam
+DEFAULT_MESSAGE_TRUNCATE_BYTES = 227  # Default message truncation size
+MESHNET_NAME_ABBREVIATION_LENGTH = 4  # Characters for short meshnet names
+SHORTNAME_FALLBACK_LENGTH = 3  # Characters for shortname fallback
+MESSAGE_PREVIEW_LENGTH = 40  # Characters for message preview in logs
+DISPLAY_NAME_DEFAULT_LENGTH = 5  # Default display name truncation
+
+# Component logger names
+COMPONENT_LOGGERS = {
+    "matrix_nio": ["nio", "nio.client", "nio.http", "nio.crypto", "nio.responses"],
+    "bleak": ["bleak", "bleak.backends"],
+    "meshtastic": [
+        "meshtastic",
+        "meshtastic.serial_interface",
+        "meshtastic.tcp_interface",
+        "meshtastic.ble_interface",
+    ],
+}
+
+# Log level styling
+LOG_LEVEL_STYLES = {
+    "DEBUG": {"color": "cyan"},
+    "INFO": {"color": "green"},
+    "WARNING": {"color": "yellow"},
+    "ERROR": {"color": "red"},
+    "CRITICAL": {"color": "red", "bold": True},
+}

mmrelay/constants/network.py

@@ -0,0 +1,45 @@
+"""
+Network and connection constants.
+
+Contains timeout values, retry limits, connection types, and other
+network-related configuration constants.
+"""
+
+# Connection types
+CONNECTION_TYPE_TCP = "tcp"
+CONNECTION_TYPE_SERIAL = "serial"
+CONNECTION_TYPE_BLE = "ble"
+CONNECTION_TYPE_NETWORK = (
+    "network"  # DEPRECATED: Legacy alias for tcp, use CONNECTION_TYPE_TCP instead
+)
+
+# Configuration keys for connection settings
+CONFIG_KEY_BLE_ADDRESS = "ble_address"
+CONFIG_KEY_SERIAL_PORT = "serial_port"
+CONFIG_KEY_HOST = "host"
+CONFIG_KEY_CONNECTION_TYPE = "connection_type"
+
+# Connection retry and timing
+DEFAULT_BACKOFF_TIME = 10  # seconds
+DEFAULT_RETRY_ATTEMPTS = 1
+INFINITE_RETRIES = 0  # 0 means infinite retries
+MINIMUM_MESSAGE_DELAY = 2.0  # Minimum delay for message queue fallback
+RECOMMENDED_MINIMUM_DELAY = (
+    2.1  # Recommended minimum delay (MINIMUM_MESSAGE_DELAY + 0.1)
+)
+
+# Matrix client timeouts
+MATRIX_EARLY_SYNC_TIMEOUT = 2000  # milliseconds
+MATRIX_MAIN_SYNC_TIMEOUT = 5000  # milliseconds
+MATRIX_ROOM_SEND_TIMEOUT = 10.0  # seconds
+MATRIX_LOGIN_TIMEOUT = 30.0  # seconds
+MATRIX_SYNC_OPERATION_TIMEOUT = 60.0  # seconds
+
+# Error codes
+ERRNO_BAD_FILE_DESCRIPTOR = 9
+
+# System detection
+SYSTEMD_INIT_SYSTEM = "systemd"
+
+# Time conversion
+MILLISECONDS_PER_SECOND = 1000

mmrelay/constants/plugins.py

@@ -0,0 +1,42 @@
+"""
+Plugin system constants.
+
+This module contains constants related to plugin security, validation,
+and configuration. These constants help ensure safe plugin loading and
+execution by defining trusted sources and dangerous patterns.
+"""
+
+from typing import Tuple
+
+# Trusted git hosting platforms for community plugins
+# These hosts are considered safe for plugin source repositories
+DEFAULT_ALLOWED_COMMUNITY_HOSTS: Tuple[str, ...] = (
+    "github.com",
+    "gitlab.com",
+    "codeberg.org",
+    "bitbucket.org",
+)
+
+# Requirement prefixes that may indicate security risks
+# These prefixes allow VCS URLs or direct URLs that could bypass package verification
+RISKY_REQUIREMENT_PREFIXES: Tuple[str, ...] = (
+    "git+",
+    "ssh://",
+    "git://",
+    "hg+",
+    "bzr+",
+    "svn+",
+    "http://",
+    "https://",
+)
+
+# Pip source flags that can be followed by URLs
+PIP_SOURCE_FLAGS: Tuple[str, ...] = (
+    "-e",
+    "--editable",
+    "-f",
+    "--find-links",
+    "-i",
+    "--index-url",
+    "--extra-index-url",
+)

mmrelay/constants/queue.py

@@ -0,0 +1,20 @@
+"""
+Message queue constants.
+
+Contains configuration values for the message queue system including
+delays, size limits, and water marks for queue management.
+"""
+
+# Message timing constants
+DEFAULT_MESSAGE_DELAY = (
+    2.5  # Set above the 2.0s firmware limit to prevent message dropping
+)
+MINIMUM_MESSAGE_DELAY = 2.1  # Minimum delay enforced to stay above firmware limit
+
+# Queue size management
+MAX_QUEUE_SIZE = 500
+QUEUE_HIGH_WATER_MARK = int(MAX_QUEUE_SIZE * 0.75)  # 75% of MAX_QUEUE_SIZE
+QUEUE_MEDIUM_WATER_MARK = int(MAX_QUEUE_SIZE * 0.50)  # 50% of MAX_QUEUE_SIZE
+
+# Queue logging thresholds
+QUEUE_LOG_THRESHOLD = 2  # Only log queue status when size >= this value

mmrelay/db_runtime.py

@@ -0,0 +1,269 @@
+"""
+Runtime utilities for managing SQLite connections used by MMRelay.
+
+Provides a DatabaseManager that centralizes connection creation,
+applies consistent pragmas, and exposes both synchronous context
+managers and async helpers for executing read/write operations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import sqlite3
+import threading
+from collections.abc import Awaitable, Callable
+from contextlib import contextmanager
+from functools import partial
+from typing import Any, Optional
+
+
+class DatabaseManager:
+    """
+    Manage SQLite connections with shared pragmas and helper execution APIs.
+
+    A separate connection is maintained per thread via thread-local storage
+    (created with `check_same_thread=False`). Write operations are serialized
+    via an RLock to ensure only one writer executes at a time. Connections are
+    tracked so they can be closed when the manager is reset.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        *,
+        enable_wal: bool = True,
+        busy_timeout_ms: int = 5000,
+        extra_pragmas: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """
+        Create a DatabaseManager configured for the given SQLite file path.
+
+        Parameters:
+            path (str): Filesystem path to the SQLite database file.
+            enable_wal (bool): If true, connections will be configured to use Write-Ahead Logging (WAL) mode.
+            busy_timeout_ms (int): Milliseconds to wait for the database when it is busy before raising an error.
+            extra_pragmas (Optional[dict[str, Any]]): Additional PRAGMA directives to apply to each connection.
+                Keys are pragma names and values are either numeric or string pragma values. Invalid pragma
+                names or values will raise when a connection is created.
+        """
+        self._path = path
+        self._enable_wal = enable_wal
+        self._busy_timeout_ms = busy_timeout_ms
+        self._extra_pragmas = extra_pragmas or {}
+
+        self._thread_local = threading.local()
+        self._write_lock = threading.RLock()
+        self._connections: set[sqlite3.Connection] = set()
+        self._connections_lock = threading.Lock()
+
+    # ------------------------------------------------------------------ #
+    # Internal helpers
+    # ------------------------------------------------------------------ #
+
+    def _create_connection(self) -> sqlite3.Connection:
+        """
+        Create and configure a new sqlite3.Connection for this manager, apply configured PRAGMA directives, and register the connection for later cleanup.
+
+        Returns:
+            sqlite3.Connection: A connection configured with the manager's pragmas and tracked by the manager.
+
+        Raises:
+            sqlite3.Error: If an SQLite error occurs during connection creation or PRAGMA setup (the partially configured connection is closed before the error is propagated).
+            ValueError: If an extra PRAGMA name or string value fails validation.
+            TypeError: If an extra PRAGMA value has an unsupported type.
+        """
+        conn = sqlite3.connect(self._path, check_same_thread=False)
+        try:
+            # Serialize PRAGMA setup to avoid concurrent WAL initialization races
+            with self._write_lock:
+                if self._busy_timeout_ms:
+                    conn.execute(f"PRAGMA busy_timeout = {int(self._busy_timeout_ms)}")
+                if self._enable_wal:
+                    # journal_mode pragma returns the applied mode; ignore result
+                    conn.execute("PRAGMA journal_mode=WAL")
+                conn.execute("PRAGMA foreign_keys=ON")
+                for pragma, value in self._extra_pragmas.items():
+                    # Validate pragma name to prevent injection.
+                    if not re.fullmatch(r"[a-zA-Z_][a-zA-Z0-9_]*", pragma):
+                        raise ValueError(f"Invalid pragma name provided: {pragma}")
+                    # Validate and sanitize value to prevent injection
+                    if isinstance(value, str):
+                        # Security: Restrict pragma string values to safe characters only.
+                        # This regex allows alphanumeric, underscore, hyphen, space, comma, period, and backslash.
+                        # We deliberately exclude forward slash and colon to prevent path injection attacks.
+                        # Backslash is allowed but trailing backslashes are blocked to prevent escape sequences.
+                        #
+                        # Security assumption: Configuration sources are trusted, but we validate defensively
+                        # to prevent accidental or malicious injection through compromised config files.
+                        # This balances security with practical SQLite pragma value requirements.
+                        if not re.fullmatch(
+                            r"[a-zA-Z0-9_\-\s,.\\\\]+", value
+                        ) or value.endswith("\\"):
+                            raise ValueError(
+                                f"Invalid or unsafe pragma value provided: {value}"
+                            )
+                        conn.execute(f"PRAGMA {pragma} = '{value}'")
+                    elif isinstance(value, bool):
+                        # Convert boolean values to ON/OFF for SQLite pragmas
+                        conn.execute(f"PRAGMA {pragma} = {'ON' if value else 'OFF'}")
+                    elif isinstance(value, (int, float)):
+                        # For numeric values, ensure they're actually numeric
+                        conn.execute(f"PRAGMA {pragma} = {value}")
+                    else:
+                        raise TypeError(f"Invalid pragma value type: {type(value)}")
+        except (sqlite3.Error, ValueError, TypeError):
+            # Ensure partially configured connection does not leak
+            conn.close()
+            raise
+
+        with self._connections_lock:
+            self._connections.add(conn)
+        return conn
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """
+        Get the thread-local SQLite connection, creating and storing a new connection if none exists.
+
+        Returns:
+            sqlite3.Connection: The per-thread SQLite connection.
+        """
+        conn = getattr(self._thread_local, "connection", None)
+        if conn is not None:
+            try:
+                # Using cursor() is a lightweight way to check if the connection is open.
+                conn.cursor().close()
+            except sqlite3.ProgrammingError:
+                # Connection is closed, so we'll create a new one.
+                with self._connections_lock:
+                    self._connections.discard(conn)
+                conn = None
+
+        if conn is None:
+            conn = self._create_connection()
+            self._thread_local.connection = conn
+        return conn
+
+    # ------------------------------------------------------------------ #
+    # Context managers
+    # ------------------------------------------------------------------ #
+
+    @contextmanager
+    def read(self) -> sqlite3.Cursor:
+        """
+        Provide a cursor for performing read-only database operations.
+
+        The cursor is obtained from the per-thread connection and is guaranteed to be closed when the context exits. This context does not commit or roll back any transactions; it is intended for queries that do not modify persistent state.
+
+        Returns:
+            sqlite3.Cursor: A cursor tied to the manager's per-thread connection.
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        try:
+            yield cursor
+        finally:
+            cursor.close()
+
+    @contextmanager
+    def write(self) -> sqlite3.Cursor:
+        """
+        Provide a context manager that yields a cursor for transactional write operations.
+
+        The yielded cursor is intended for executing modifying statements. The transaction is committed when the context exits normally and rolled back if an exception is raised. Write operations are serialized across threads using the manager's write lock, and the cursor is closed on exit.
+
+        Returns:
+            cursor (sqlite3.Cursor): Cursor for executing write statements; committed on success, rolled back on exception.
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        with self._write_lock:
+            try:
+                yield cursor
+                conn.commit()
+            except Exception:
+                conn.rollback()
+                raise
+            finally:
+                cursor.close()
+
+    # ------------------------------------------------------------------ #
+    # Execution helpers
+    # ------------------------------------------------------------------ #
+
+    def run_sync(
+        self,
+        func: Callable[[sqlite3.Cursor], Any],
+        *,
+        write: bool = False,
+    ) -> Any:
+        """
+        Execute a callable with a managed SQLite cursor.
+
+        Run `func` with a cursor provided by the manager; when `write` is True, the callable is executed inside a write transaction that will be committed on success and rolled back on exception.
+
+        Parameters:
+            func (Callable[[sqlite3.Cursor], Any]): A callable that receives a `sqlite3.Cursor` and returns a result.
+            write (bool): If True, execute `func` in a transactional write context; otherwise use a read-only cursor. Defaults to False.
+
+        Returns:
+            Any: The value returned by `func`.
+        """
+        context = self.write if write else self.read
+        with context() as cursor:
+            return func(cursor)
+
+    async def run_async(
+        self,
+        func: Callable[[sqlite3.Cursor], Any],
+        *,
+        write: bool = False,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+    ) -> Any:
+        """
+        Run a database callable in the event loop's executor and return its result.
+
+        Parameters:
+            func (Callable[[sqlite3.Cursor], Any]): Callable that will be invoked with a managed SQLite cursor.
+            write (bool, optional): If true, the callable receives a cursor from a transactional write context; otherwise a read-only context is used. Defaults to False.
+            loop (asyncio.AbstractEventLoop, optional): Event loop whose executor will run the callable. If omitted, the running event loop is used.
+
+        Returns:
+            Any: The value returned by `func` when invoked with the cursor.
+        """
+        loop = loop or asyncio.get_running_loop()
+        executor_func = partial(self.run_sync, func, write=write)
+        return await loop.run_in_executor(None, executor_func)
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle
+    # ------------------------------------------------------------------ #
+
+    def close(self) -> None:
+        """
+        Close and clean up all tracked SQLite connections.
+
+        Removes every connection from the manager's internal registry, attempts to close each connection (suppressing sqlite3.Error), and clears the current thread's stored connection reference.
+        """
+        with self._connections_lock:
+            connections = list(self._connections)
+            self._connections.clear()
+            # Close connections while holding the lock to prevent race conditions
+            # where new connections might be created and missed during cleanup.
+            for conn in connections:
+                try:
+                    conn.close()
+                except sqlite3.Error:
+                    pass
+
+        # Clear thread-local references in the current thread
+        if hasattr(self._thread_local, "connection"):
+            try:
+                del self._thread_local.connection
+            except AttributeError:
+                pass
+
+
+# Convenience alias for type hints
+DbCallable = Callable[[sqlite3.Cursor], Any]
+AsyncDbCallable = Callable[[sqlite3.Cursor], Awaitable[Any]]