da2-mcp-socket 0.2.0__py3-none-any.whl

mcp_socket/socket_manager.py

@@ -0,0 +1,1103 @@
+"""
+Copyright (c) 2026 Danny, DA2 Studio (https://da2.35g.tw)
+Socket Manager - Core TCP/IP socket connection management logic.
+
+Handles socket connection, disconnection, and data transmission.
+"""
+
+import logging
+import socket
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+logger = logging.getLogger("mcp-socket")
+
+
+@dataclass
+class SocketConfig:
+    """Socket connection configuration."""
+    host: str
+    port: int
+    timeout: float = 10.0
+    read_timeout: float = 5.0
+    buffer_size: int = 4096
+    max_buffer_packets: int = 100  # Maximum packets in buffer
+    auto_listen: bool = True  # Auto start background listener
+
+
+@dataclass
+class ReceiveProtocol:
+    """Receive protocol configuration for packet parsing."""
+    mode: str = "line"  # raw, line, packet (default: line mode with CRLF)
+    start_delimiter: bytes = b""  # Start of packet delimiter (default: empty)
+    end_delimiter: bytes = b"\r\n"  # End of packet delimiter (default: CRLF = 0D0A)
+    include_delimiters: bool = False  # Include delimiters in received data
+
+
+@dataclass
+class OpenSocket:
+    """Represents an open socket connection."""
+    connection_id: str
+    config: SocketConfig
+    socket: socket.socket
+    protocol: ReceiveProtocol = field(default_factory=ReceiveProtocol)
+    opened_at: float = field(default_factory=time.time)
+    bytes_sent: int = 0
+    bytes_received: int = 0
+    receive_buffer: bytes = b""  # Buffer for partial packet data
+    # Background listener fields
+    packet_buffer: list = field(default_factory=list)  # Parsed packets buffer
+    listener_thread: Optional[threading.Thread] = None
+    listener_running: bool = False
+    overflow_count: int = 0  # Count of dropped packets due to overflow
+    _packet_lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+class SocketManager:
+    """Manages TCP/IP socket connections and operations."""
+
+    def __init__(self):
+        """Initialize the socket manager."""
+        self._connections: dict[str, OpenSocket] = {}
+        self._lock = threading.Lock()
+
+    def _generate_connection_id(self, host: str, port: int) -> str:
+        """Generate a unique connection ID."""
+        return f"{host}:{port}_{uuid.uuid4().hex[:8]}"
+
+    def connect(
+        self,
+        host: str,
+        port: int,
+        timeout: float = 10.0,
+        read_timeout: float = 5.0,
+        buffer_size: int = 4096,
+        max_buffer_packets: int = 100,
+        auto_listen: bool = False
+    ) -> dict[str, Any]:
+        """Connect to a TCP server.
+        
+        Args:
+            host: Target host (IP address or hostname).
+            port: Target port number.
+            timeout: Connection timeout in seconds.
+            read_timeout: Read timeout in seconds.
+            buffer_size: Buffer size for receiving data.
+            max_buffer_packets: Maximum packets to buffer (default 100).
+            auto_listen: Auto start background listener after set_protocol.
+            
+        Returns:
+            Dictionary containing success status and connection info.
+        """
+        with self._lock:
+            try:
+                # Validate parameters
+                if not host:
+                    return {
+                        "success": False,
+                        "error": "Host cannot be empty",
+                        "error_type": "InvalidParameter"
+                    }
+                
+                if not (1 <= port <= 65535):
+                    return {
+                        "success": False,
+                        "error": f"Invalid port: {port}. Must be between 1 and 65535.",
+                        "error_type": "InvalidParameter"
+                    }
+                
+                # Create socket
+                sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                sock.settimeout(timeout)
+                
+                # Connect to server
+                logger.info(f"Connecting to {host}:{port}...")
+                sock.connect((host, port))
+                
+                # Set read timeout after connection
+                sock.settimeout(read_timeout)
+                
+                # Create configuration
+                config = SocketConfig(
+                    host=host,
+                    port=port,
+                    timeout=timeout,
+                    read_timeout=read_timeout,
+                    buffer_size=buffer_size,
+                    max_buffer_packets=max_buffer_packets,
+                    auto_listen=auto_listen
+                )
+                
+                # Generate connection ID
+                connection_id = self._generate_connection_id(host, port)
+                
+                # Store the connection
+                self._connections[connection_id] = OpenSocket(
+                    connection_id=connection_id,
+                    config=config,
+                    socket=sock
+                )
+                
+                logger.info(f"Connected to {host}:{port} with ID: {connection_id}")
+                
+                return {
+                    "success": True,
+                    "message": f"Connected to {host}:{port}",
+                    "connection_id": connection_id,
+                    "config": {
+                        "host": host,
+                        "port": port,
+                        "timeout": timeout,
+                        "read_timeout": read_timeout,
+                        "buffer_size": buffer_size,
+                        "max_buffer_packets": max_buffer_packets,
+                        "auto_listen": auto_listen
+                    }
+                }
+                
+            except socket.timeout:
+                logger.error(f"Connection to {host}:{port} timed out")
+                return {
+                    "success": False,
+                    "error": f"Connection to {host}:{port} timed out after {timeout} seconds",
+                    "error_type": "ConnectionTimeout"
+                }
+            except socket.gaierror as e:
+                logger.error(f"Failed to resolve host {host}: {e}")
+                return {
+                    "success": False,
+                    "error": f"Failed to resolve host: {host}",
+                    "error_type": "HostResolutionError"
+                }
+            except ConnectionRefusedError:
+                logger.error(f"Connection refused by {host}:{port}")
+                return {
+                    "success": False,
+                    "error": f"Connection refused by {host}:{port}",
+                    "error_type": "ConnectionRefused"
+                }
+            except Exception as e:
+                logger.error(f"Failed to connect to {host}:{port}: {e}")
+                return {
+                    "success": False,
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                }
+
+    def disconnect(self, connection_id: str) -> dict[str, Any]:
+        """Close a socket connection.
+        
+        Args:
+            connection_id: The connection ID to close.
+            
+        Returns:
+            Dictionary containing success status and statistics.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            try:
+                conn = self._connections[connection_id]
+                conn.socket.close()
+                
+                # Calculate statistics
+                duration = time.time() - conn.opened_at
+                
+                del self._connections[connection_id]
+                
+                logger.info(f"Disconnected: {connection_id}")
+                
+                return {
+                    "success": True,
+                    "message": f"Connection {connection_id} closed",
+                    "connection_id": connection_id,
+                    "statistics": {
+                        "duration_seconds": round(duration, 2),
+                        "bytes_sent": conn.bytes_sent,
+                        "bytes_received": conn.bytes_received
+                    }
+                }
+                
+            except Exception as e:
+                logger.error(f"Error disconnecting {connection_id}: {e}")
+                return {
+                    "success": False,
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                }
+
+    def disconnect_all(self) -> dict[str, Any]:
+        """Close all socket connections.
+        
+        Returns:
+            Dictionary containing success status and closed connections.
+        """
+        with self._lock:
+            closed_connections = []
+            errors = []
+            
+            for conn_id in list(self._connections.keys()):
+                try:
+                    self._connections[conn_id].socket.close()
+                    closed_connections.append(conn_id)
+                except Exception as e:
+                    errors.append({"connection_id": conn_id, "error": str(e)})
+            
+            self._connections.clear()
+            
+            return {
+                "success": len(errors) == 0,
+                "closed_connections": closed_connections,
+                "count": len(closed_connections),
+                "errors": errors if errors else None
+            }
+
+    def get_connection_status(self, connection_id: Optional[str] = None) -> dict[str, Any]:
+        """Get status of connection(s).
+        
+        Args:
+            connection_id: Specific connection to query, or None for all.
+            
+        Returns:
+            Dictionary containing connection status information.
+        """
+        with self._lock:
+            if connection_id:
+                if connection_id not in self._connections:
+                    return {
+                        "success": False,
+                        "error": f"Connection {connection_id} not found",
+                        "error_type": "ConnectionNotFound"
+                    }
+                
+                conn = self._connections[connection_id]
+                return {
+                    "success": True,
+                    "connection_id": connection_id,
+                    "config": {
+                        "host": conn.config.host,
+                        "port": conn.config.port,
+                        "timeout": conn.config.timeout,
+                        "read_timeout": conn.config.read_timeout,
+                        "buffer_size": conn.config.buffer_size
+                    },
+                    "statistics": {
+                        "opened_at": conn.opened_at,
+                        "duration_seconds": round(time.time() - conn.opened_at, 2),
+                        "bytes_sent": conn.bytes_sent,
+                        "bytes_received": conn.bytes_received
+                    }
+                }
+            else:
+                # Return all connections
+                connections_status = {}
+                for conn_id, conn in self._connections.items():
+                    connections_status[conn_id] = {
+                        "host": conn.config.host,
+                        "port": conn.config.port,
+                        "bytes_sent": conn.bytes_sent,
+                        "bytes_received": conn.bytes_received,
+                        "duration_seconds": round(time.time() - conn.opened_at, 2)
+                    }
+                
+                return {
+                    "success": True,
+                    "connections": connections_status,
+                    "count": len(connections_status)
+                }
+
+    def send_data(
+        self,
+        connection_id: str,
+        data: str,
+        encoding: str = "utf-8",
+        as_hex: bool = False
+    ) -> dict[str, Any]:
+        """Send data through a socket connection.
+        
+        Args:
+            connection_id: The connection to send through.
+            data: Data to send (string or hex string).
+            encoding: Text encoding (default utf-8).
+            as_hex: If True, interpret data as hex string.
+            
+        Returns:
+            Dictionary containing success status and bytes sent.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            try:
+                conn = self._connections[connection_id]
+                
+                if as_hex:
+                    # Parse hex string
+                    hex_str = data.replace(" ", "").replace("0x", "").replace(",", "")
+                    try:
+                        byte_data = bytes.fromhex(hex_str)
+                    except ValueError as e:
+                        return {
+                            "success": False,
+                            "error": f"Invalid hex string: {e}",
+                            "error_type": "InvalidHexString"
+                        }
+                else:
+                    byte_data = data.encode(encoding)
+                
+                bytes_sent = conn.socket.send(byte_data)
+                conn.bytes_sent += bytes_sent
+                
+                logger.debug(f"Sent {bytes_sent} bytes through {connection_id}")
+                
+                return {
+                    "success": True,
+                    "connection_id": connection_id,
+                    "bytes_sent": bytes_sent,
+                    "data_hex": byte_data.hex().upper(),
+                    "data_preview": data[:50] + ("..." if len(data) > 50 else "")
+                }
+                
+            except socket.timeout:
+                return {
+                    "success": False,
+                    "error": "Send timeout",
+                    "error_type": "SendTimeout"
+                }
+            except BrokenPipeError:
+                return {
+                    "success": False,
+                    "error": "Connection broken (remote end closed)",
+                    "error_type": "BrokenPipe"
+                }
+            except Exception as e:
+                logger.error(f"Error sending to {connection_id}: {e}")
+                return {
+                    "success": False,
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                }
+
+    def receive_data(
+        self,
+        connection_id: str,
+        size: Optional[int] = None,
+        timeout: Optional[float] = None,
+        as_hex: bool = False
+    ) -> dict[str, Any]:
+        """Receive data from a socket connection.
+        
+        Args:
+            connection_id: The connection to receive from.
+            size: Maximum bytes to receive (default: buffer_size).
+            timeout: Read timeout in seconds (None = use connection default).
+            as_hex: If True, return data as hex string only.
+            
+        Returns:
+            Dictionary containing success status and received data.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            try:
+                conn = self._connections[connection_id]
+                recv_size = size or conn.config.buffer_size
+                
+                # Temporarily change timeout if specified
+                original_timeout = conn.socket.gettimeout()
+                if timeout is not None:
+                    conn.socket.settimeout(timeout)
+                
+                try:
+                    data = conn.socket.recv(recv_size)
+                finally:
+                    if timeout is not None:
+                        conn.socket.settimeout(original_timeout)
+                
+                conn.bytes_received += len(data)
+                
+                result = {
+                    "success": True,
+                    "connection_id": connection_id,
+                    "bytes_received": len(data),
+                    "data_hex": data.hex().upper() if data else ""
+                }
+                
+                # Try to decode as text
+                if not as_hex:
+                    try:
+                        result["data_text"] = data.decode("utf-8", errors="replace")
+                    except:
+                        result["data_text"] = None
+                
+                return result
+                
+            except socket.timeout:
+                return {
+                    "success": True,
+                    "connection_id": connection_id,
+                    "bytes_received": 0,
+                    "data_hex": "",
+                    "data_text": "",
+                    "message": "No data received (timeout)"
+                }
+            except Exception as e:
+                logger.error(f"Error receiving from {connection_id}: {e}")
+                return {
+                    "success": False,
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                }
+
+    def receive_until(
+        self,
+        connection_id: str,
+        terminator: str = "\n",
+        size: int = 4096,
+        timeout: Optional[float] = None
+    ) -> dict[str, Any]:
+        """Receive data until a specific terminator is found.
+        
+        Args:
+            connection_id: The connection to receive from.
+            terminator: Terminator string to look for.
+            size: Maximum bytes to receive.
+            timeout: Read timeout in seconds.
+            
+        Returns:
+            Dictionary containing success status and received data.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            try:
+                conn = self._connections[connection_id]
+                terminator_bytes = terminator.encode("utf-8")
+                
+                # Temporarily change timeout if specified
+                original_timeout = conn.socket.gettimeout()
+                if timeout is not None:
+                    conn.socket.settimeout(timeout)
+                
+                try:
+                    buffer = b""
+                    while len(buffer) < size:
+                        chunk = conn.socket.recv(1)
+                        if not chunk:
+                            break
+                        buffer += chunk
+                        if buffer.endswith(terminator_bytes):
+                            break
+                finally:
+                    if timeout is not None:
+                        conn.socket.settimeout(original_timeout)
+                
+                conn.bytes_received += len(buffer)
+                
+                return {
+                    "success": True,
+                    "connection_id": connection_id,
+                    "data_text": buffer.decode("utf-8", errors="replace"),
+                    "data_hex": buffer.hex().upper(),
+                    "bytes_received": len(buffer)
+                }
+                
+            except socket.timeout:
+                return {
+                    "success": True,
+                    "connection_id": connection_id,
+                    "bytes_received": 0,
+                    "data_hex": "",
+                    "data_text": "",
+                    "message": "No data received (timeout)"
+                }
+            except Exception as e:
+                logger.error(f"Error receiving from {connection_id}: {e}")
+                return {
+                    "success": False,
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                }
+
+    def receive_line(
+        self,
+        connection_id: str,
+        timeout: Optional[float] = None,
+        encoding: str = "utf-8"
+    ) -> dict[str, Any]:
+        """Receive a line (until newline) from a socket connection.
+        
+        Args:
+            connection_id: The connection to receive from.
+            timeout: Read timeout in seconds.
+            encoding: Text encoding for decoding.
+            
+        Returns:
+            Dictionary containing success status and received line.
+        """
+        result = self.receive_until(
+            connection_id=connection_id,
+            terminator="\n",
+            timeout=timeout
+        )
+        
+        if result.get("success") and result.get("data_text"):
+            # Strip trailing newline characters
+            result["line"] = result["data_text"].rstrip("\r\n")
+        
+        return result
+
+    def set_protocol(
+        self,
+        connection_id: str,
+        mode: str = "raw",
+        start_delimiter: Optional[str] = None,
+        end_delimiter: Optional[str] = None,
+        start_delimiter_hex: Optional[str] = None,
+        end_delimiter_hex: Optional[str] = None,
+        include_delimiters: bool = False
+    ) -> dict[str, Any]:
+        """Set the receive protocol for a connection.
+        
+        Configure how data should be received and parsed.
+        
+        Args:
+            connection_id: The connection to configure.
+            mode: Receive mode - 'raw', 'line', or 'packet'.
+                  - raw: Receive data as-is
+                  - line: Receive data line by line (end_delimiter = newline)
+                  - packet: Parse packets using start/end delimiters
+            start_delimiter: Start of packet delimiter (text format).
+            end_delimiter: End of packet delimiter (text format).
+            start_delimiter_hex: Start delimiter in hex format (e.g., "0A").
+            end_delimiter_hex: End delimiter in hex format (e.g., "0D0A").
+            include_delimiters: Include delimiters in received data.
+            
+        Returns:
+            Dictionary containing success status and protocol settings.
+            
+        Examples:
+            - set_protocol("conn_id", mode="line")  # Line mode (\\n terminator)
+            - set_protocol("conn_id", mode="packet", end_delimiter_hex="0D0A")
+            - set_protocol("conn_id", mode="packet", start_delimiter_hex="0A", end_delimiter_hex="0D0A")
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            # Validate mode
+            valid_modes = ["raw", "line", "packet"]
+            if mode not in valid_modes:
+                return {
+                    "success": False,
+                    "error": f"Invalid mode: {mode}. Valid options: {valid_modes}",
+                    "error_type": "InvalidParameter"
+                }
+            
+            # Parse delimiters
+            start_bytes = b""
+            end_bytes = b"\n"  # Default for line mode
+            
+            if mode == "packet":
+                # Parse start delimiter
+                if start_delimiter_hex:
+                    try:
+                        start_bytes = bytes.fromhex(start_delimiter_hex.replace(" ", ""))
+                    except ValueError as e:
+                        return {
+                            "success": False,
+                            "error": f"Invalid start_delimiter_hex: {e}",
+                            "error_type": "InvalidHexString"
+                        }
+                elif start_delimiter:
+                    start_bytes = start_delimiter.encode("utf-8")
+                
+                # Parse end delimiter
+                if end_delimiter_hex:
+                    try:
+                        end_bytes = bytes.fromhex(end_delimiter_hex.replace(" ", ""))
+                    except ValueError as e:
+                        return {
+                            "success": False,
+                            "error": f"Invalid end_delimiter_hex: {e}",
+                            "error_type": "InvalidHexString"
+                        }
+                elif end_delimiter:
+                    end_bytes = end_delimiter.encode("utf-8")
+            
+            # Update protocol
+            conn = self._connections[connection_id]
+            conn.protocol = ReceiveProtocol(
+                mode=mode,
+                start_delimiter=start_bytes,
+                end_delimiter=end_bytes,
+                include_delimiters=include_delimiters
+            )
+            
+            # Clear receive buffer when changing protocol
+            conn.receive_buffer = b""
+            
+            logger.info(f"Set protocol for {connection_id}: mode={mode}, start={start_bytes.hex().upper()}, end={end_bytes.hex().upper()}")
+            
+            return {
+                "success": True,
+                "connection_id": connection_id,
+                "protocol": {
+                    "mode": mode,
+                    "start_delimiter_hex": start_bytes.hex().upper() if start_bytes else "",
+                    "end_delimiter_hex": end_bytes.hex().upper(),
+                    "include_delimiters": include_delimiters
+                }
+            }
+
+    def receive_packet(
+        self,
+        connection_id: str,
+        timeout: Optional[float] = None,
+        max_size: int = 4096
+    ) -> dict[str, Any]:
+        """Receive a complete packet based on the configured protocol.
+        
+        Uses the start/end delimiters configured via set_protocol().
+        For packet mode: waits for data between start_delimiter and end_delimiter.
+        For line mode: equivalent to receive_line().
+        For raw mode: equivalent to receive_data().
+        
+        Args:
+            connection_id: The connection to receive from.
+            timeout: Read timeout in seconds.
+            max_size: Maximum packet size to prevent memory issues.
+            
+        Returns:
+            Dictionary containing success status, packet data, and metadata.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            conn = self._connections[connection_id]
+            protocol = conn.protocol
+            
+            # For raw mode, just receive data
+            if protocol.mode == "raw":
+                # Release lock temporarily for receive_data
+                pass
+        
+        # Handle different modes (outside lock to avoid deadlock with receive_data)
+        if protocol.mode == "raw":
+            return self.receive_data(connection_id, size=max_size, timeout=timeout)
+        elif protocol.mode == "line":
+            return self.receive_line(connection_id, timeout=timeout)
+        
+        # Packet mode - parse with start/end delimiters
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            conn = self._connections[connection_id]
+            protocol = conn.protocol
+            start_delim = protocol.start_delimiter
+            end_delim = protocol.end_delimiter
+            
+            try:
+                original_timeout = conn.socket.gettimeout()
+                if timeout is not None:
+                    conn.socket.settimeout(timeout)
+                
+                try:
+                    buffer = conn.receive_buffer
+                    packet_found = False
+                    start_pos = -1
+                    end_pos = -1
+                    
+                    while len(buffer) < max_size:
+                        # Check if we already have a complete packet in buffer
+                        if start_delim:
+                            start_pos = buffer.find(start_delim)
+                            if start_pos >= 0:
+                                search_start = start_pos + len(start_delim)
+                                end_pos = buffer.find(end_delim, search_start)
+                                if end_pos >= 0:
+                                    packet_found = True
+                                    break
+                        else:
+                            # No start delimiter, just look for end
+                            end_pos = buffer.find(end_delim)
+                            if end_pos >= 0:
+                                start_pos = 0
+                                packet_found = True
+                                break
+                        
+                        # Need more data
+                        try:
+                            chunk = conn.socket.recv(conn.config.buffer_size)
+                            if not chunk:
+                                break  # Connection closed
+                            buffer += chunk
+                        except socket.timeout:
+                            break
+                    
+                    # Update connection buffer
+                    if packet_found:
+                        # Extract packet
+                        if start_delim:
+                            data_start = start_pos + len(start_delim)
+                        else:
+                            data_start = 0
+                        
+                        packet_data = buffer[data_start:end_pos]
+                        
+                        # Include delimiters if configured
+                        if protocol.include_delimiters:
+                            if start_delim:
+                                packet_with_delim = start_delim + packet_data + end_delim
+                            else:
+                                packet_with_delim = packet_data + end_delim
+                        else:
+                            packet_with_delim = packet_data
+                        
+                        # Remove processed data from buffer
+                        conn.receive_buffer = buffer[end_pos + len(end_delim):]
+                        conn.bytes_received += len(packet_with_delim)
+                        
+                        return {
+                            "success": True,
+                            "connection_id": connection_id,
+                            "packet_found": True,
+                            "data_hex": packet_with_delim.hex().upper(),
+                            "data_text": packet_with_delim.decode("utf-8", errors="replace"),
+                            "payload_hex": packet_data.hex().upper(),
+                            "payload_text": packet_data.decode("utf-8", errors="replace"),
+                            "bytes_received": len(packet_with_delim)
+                        }
+                    else:
+                        # No complete packet found, save buffer for next call
+                        conn.receive_buffer = buffer
+                        return {
+                            "success": True,
+                            "connection_id": connection_id,
+                            "packet_found": False,
+                            "message": "No complete packet received (timeout or max_size reached)",
+                            "buffer_size": len(buffer)
+                        }
+                        
+                finally:
+                    if timeout is not None:
+                        conn.socket.settimeout(original_timeout)
+                        
+            except Exception as e:
+                logger.error(f"Error receiving packet from {connection_id}: {e}")
+                return {
+                    "success": False,
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                }
+
+    def get_protocol(self, connection_id: str) -> dict[str, Any]:
+        """Get the current receive protocol settings for a connection.
+        
+        Args:
+            connection_id: The connection to query.
+            
+        Returns:
+            Dictionary containing protocol settings.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            conn = self._connections[connection_id]
+            protocol = conn.protocol
+            
+            return {
+                "success": True,
+                "connection_id": connection_id,
+                "protocol": {
+                    "mode": protocol.mode,
+                    "start_delimiter_hex": protocol.start_delimiter.hex().upper() if protocol.start_delimiter else "",
+                    "end_delimiter_hex": protocol.end_delimiter.hex().upper(),
+                    "include_delimiters": protocol.include_delimiters
+                },
+                "buffer_size": len(conn.receive_buffer)
+            }
+
+    # ==================== Background Listener ====================
+
+    def _listener_loop(self, connection_id: str) -> None:
+        """Background thread loop for receiving packets."""
+        logger.info(f"Starting background listener for {connection_id}")
+        
+        while True:
+            with self._lock:
+                if connection_id not in self._connections:
+                    logger.info(f"Connection {connection_id} closed, stopping listener")
+                    return
+                conn = self._connections[connection_id]
+                if not conn.listener_running:
+                    logger.info(f"Listener stopped for {connection_id}")
+                    return
+                
+                protocol = conn.protocol
+                start_delim = protocol.start_delimiter
+                end_delim = protocol.end_delimiter
+                max_packets = conn.config.max_buffer_packets
+            
+            try:
+                # Receive data outside lock to avoid blocking
+                with self._lock:
+                    if connection_id not in self._connections:
+                        return
+                    conn = self._connections[connection_id]
+                    sock = conn.socket
+                    buffer = conn.receive_buffer
+                
+                # Try to receive data with short timeout
+                try:
+                    sock.settimeout(0.5)
+                    chunk = sock.recv(conn.config.buffer_size)
+                    if chunk:
+                        buffer += chunk
+                except socket.timeout:
+                    pass
+                except (ConnectionResetError, BrokenPipeError, OSError):
+                    logger.warning(f"Connection {connection_id} lost")
+                    with self._lock:
+                        if connection_id in self._connections:
+                            self._connections[connection_id].listener_running = False
+                    return
+                
+                # Parse packets from buffer
+                packets_found = []
+                while True:
+                    if start_delim:
+                        start_pos = buffer.find(start_delim)
+                        if start_pos < 0:
+                            break
+                        search_start = start_pos + len(start_delim)
+                        end_pos = buffer.find(end_delim, search_start)
+                        if end_pos < 0:
+                            break
+                        # Extract packet data
+                        data_start = start_pos + len(start_delim)
+                        packet_data = buffer[data_start:end_pos]
+                        # Include delimiters if configured
+                        if protocol.include_delimiters:
+                            packet_with_delim = start_delim + packet_data + end_delim
+                        else:
+                            packet_with_delim = packet_data
+                        packets_found.append(packet_with_delim)
+                        buffer = buffer[end_pos + len(end_delim):]
+                    else:
+                        # No start delimiter
+                        end_pos = buffer.find(end_delim)
+                        if end_pos < 0:
+                            break
+                        packet_data = buffer[:end_pos]
+                        if protocol.include_delimiters:
+                            packet_with_delim = packet_data + end_delim
+                        else:
+                            packet_with_delim = packet_data
+                        packets_found.append(packet_with_delim)
+                        buffer = buffer[end_pos + len(end_delim):]
+                
+                # Store parsed packets
+                with self._lock:
+                    if connection_id not in self._connections:
+                        return
+                    conn = self._connections[connection_id]
+                    conn.receive_buffer = buffer
+                    
+                    with conn._packet_lock:
+                        for packet in packets_found:
+                            conn.bytes_received += len(packet)
+                            if len(conn.packet_buffer) >= max_packets:
+                                # Drop oldest (drop_oldest policy)
+                                conn.packet_buffer.pop(0)
+                                conn.overflow_count += 1
+                            conn.packet_buffer.append({
+                                "data_hex": packet.hex().upper(),
+                                "data_text": packet.decode("utf-8", errors="replace"),
+                                "timestamp": time.time(),
+                                "size": len(packet)
+                            })
+                
+            except Exception as e:
+                logger.error(f"Listener error for {connection_id}: {e}")
+                time.sleep(0.5)
+
+    def start_listening(self, connection_id: str) -> dict[str, Any]:
+        """Start background packet listener for a connection.
+        
+        Args:
+            connection_id: The connection ID.
+            
+        Returns:
+            Dictionary containing success status.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            conn = self._connections[connection_id]
+            
+            if conn.listener_running:
+                return {
+                    "success": True,
+                    "message": "Listener already running",
+                    "connection_id": connection_id
+                }
+            
+            conn.listener_running = True
+            conn.listener_thread = threading.Thread(
+                target=self._listener_loop,
+                args=(connection_id,),
+                daemon=True
+            )
+            conn.listener_thread.start()
+            
+            logger.info(f"Started listener for {connection_id}")
+            
+            return {
+                "success": True,
+                "message": "Background listener started",
+                "connection_id": connection_id,
+                "max_buffer_packets": conn.config.max_buffer_packets
+            }
+
+    def stop_listening(self, connection_id: str) -> dict[str, Any]:
+        """Stop background packet listener for a connection.
+        
+        Args:
+            connection_id: The connection ID.
+            
+        Returns:
+            Dictionary containing success status.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            conn = self._connections[connection_id]
+            conn.listener_running = False
+            
+            logger.info(f"Stopped listener for {connection_id}")
+            
+            return {
+                "success": True,
+                "message": "Background listener stopped",
+                "connection_id": connection_id
+            }
+
+    def get_packets(self, connection_id: str, clear: bool = True) -> dict[str, Any]:
+        """Get all buffered packets from a connection.
+        
+        Args:
+            connection_id: The connection ID.
+            clear: Clear buffer after getting packets (default True).
+            
+        Returns:
+            Dictionary containing packets array.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            conn = self._connections[connection_id]
+            
+            with conn._packet_lock:
+                packets = list(conn.packet_buffer)
+                if clear:
+                    conn.packet_buffer.clear()
+            
+            return {
+                "success": True,
+                "connection_id": connection_id,
+                "packets": packets,
+                "count": len(packets),
+                "overflow_count": conn.overflow_count
+            }
+
+    def get_buffer_status(self, connection_id: str) -> dict[str, Any]:
+        """Get buffer status for a connection.
+        
+        Args:
+            connection_id: The connection ID.
+            
+        Returns:
+            Dictionary containing buffer status.
+        """
+        with self._lock:
+            if connection_id not in self._connections:
+                return {
+                    "success": False,
+                    "error": f"Connection {connection_id} not found",
+                    "error_type": "ConnectionNotFound"
+                }
+            
+            conn = self._connections[connection_id]
+            
+            with conn._packet_lock:
+                count = len(conn.packet_buffer)
+            
+            return {
+                "success": True,
+                "connection_id": connection_id,
+                "buffer": {
+                    "count": count,
+                    "max": conn.config.max_buffer_packets,
+                    "overflow_count": conn.overflow_count,
+                    "raw_buffer_size": len(conn.receive_buffer)
+                },
+                "listener_running": conn.listener_running
+            }