declib 3.8.0__py3-none-any.whl

declib/api/decompiler_server.py

@@ -0,0 +1,782 @@
+# Note to reader: most of this code was generated by Claude 4.5. It may contain errors and was designed
+# in tandem with decompiler_client.py and the tests/test_client_server.py file. This comment will be
+# removed when the majority of the file is owned by a human author.
+
+import logging
+import pickle
+import queue
+import socket
+import struct
+import threading
+import time
+import tempfile
+import os
+from typing import Optional, Dict, Any, List
+
+from declib.api.decompiler_interface import DecompilerInterface
+from declib.api import server_registry
+from declib.artifacts.formatting import ArtifactFormat
+
+_l = logging.getLogger(__name__)
+
+# JSON, not TOML: the `toml` package's encoder mangles raw `\x` escapes,
+# which show up in decompilation text for C char literals like `'\x01'`.
+_WIRE_FMT = ArtifactFormat.JSON
+
+# Sentinel used to poke the main-thread dispatcher awake on shutdown.
+_MAIN_THREAD_SHUTDOWN = object()
+
+
+class _MainThreadError:
+    """Wrap exceptions that occurred on the main thread so the waiting client
+    thread can re-raise them after receiving the result."""
+
+    __slots__ = ("exc",)
+
+    def __init__(self, exc: BaseException):
+        self.exc = exc
+
+
+class SocketProtocol:
+    """Helper class for socket protocol message framing"""
+    
+    @staticmethod
+    def send_message(sock: socket.socket, data: Any) -> None:
+        """Send a pickled message with length prefix"""
+        try:
+            pickled_data = pickle.dumps(data)
+            msg_len = len(pickled_data)
+
+            # Send 4-byte length prefix
+            sock.sendall(struct.pack('!I', msg_len))
+            # Send pickled data
+            sock.sendall(pickled_data)
+        except (ConnectionError, BrokenPipeError, OSError) as e:
+            # Expected during shutdown when socket is closed, just re-raise
+            raise
+        except Exception as e:
+            # Unexpected error - log it
+            _l.error(f"Failed to send message (pickle.dumps): {e}")
+            _l.error(f"Data type: {type(data)}")
+            if hasattr(data, '__dict__'):
+                _l.error(f"Data dict: {data.__dict__}")
+            raise
+    
+    @staticmethod
+    def recv_message(sock: socket.socket) -> Any:
+        """Receive a pickled message with length prefix"""
+        pickled_data = b''
+        try:
+            # Receive 4-byte length prefix
+            len_data = sock.recv(4)
+            if len(len_data) != 4:
+                raise ConnectionError("Failed to receive message length")
+
+            msg_len = struct.unpack('!I', len_data)[0]
+
+            # Receive the pickled data
+            while len(pickled_data) < msg_len:
+                chunk = sock.recv(msg_len - len(pickled_data))
+                if not chunk:
+                    raise ConnectionError("Connection closed while receiving message")
+                pickled_data += chunk
+
+            return pickle.loads(pickled_data)
+        except (ConnectionError, socket.timeout):
+            # Expected during shutdown or normal timeout, just re-raise without logging
+            raise
+        except Exception as e:
+            # Unexpected error - log it
+            _l.error(f"Failed to receive message (pickle.loads): {e}")
+            if pickled_data:
+                _l.error(f"Received {len(pickled_data)} bytes of pickle data")
+            raise
+
+
+class SocketServerHandler:
+    """Handler for individual client connections"""
+
+    def __init__(self, deci: DecompilerInterface, server: 'DecompilerServer' = None):
+        self.deci = deci
+        self.server = server
+        self._light_caches = {}
+        self._cache_lock = threading.Lock()
+        self._cache_ttl = 10.0
+
+    def _dispatch(self, func, *args, **kwargs):
+        """Call ``func`` either directly or via the server's main-thread queue.
+
+        Backends like IDA reject cross-thread API access, so the server
+        declares ``_requires_main_thread`` and we route everything through
+        its dispatcher. For thread-safe backends (ghidra headless, angr,
+        binja) we short-circuit to a direct call.
+        """
+        if self.server is None or not self.server.requires_main_thread:
+            return func(*args, **kwargs)
+        return self.server.run_on_main_thread(func, *args, **kwargs)
+    
+    def handle_client(self, client_socket: socket.socket, addr: str):
+        """Handle a client connection"""
+        _l.info(f"Client connected: {addr}")
+
+        try:
+            while True:
+                try:
+                    request = SocketProtocol.recv_message(client_socket)
+                    response = self._process_request(request, client_socket=client_socket)
+                    SocketProtocol.send_message(client_socket, response)
+                except ConnectionError:
+                    # Client disconnected
+                    break
+                except Exception as e:
+                    # Send error response
+                    error_response = {"error": str(e), "type": type(e).__name__}
+                    try:
+                        SocketProtocol.send_message(client_socket, error_response)
+                    except:
+                        break
+        finally:
+            # Remove from event subscribers if subscribed
+            if self.server:
+                with self.server._event_subscribers_lock:
+                    if client_socket in self.server._event_subscribers:
+                        self.server._event_subscribers.remove(client_socket)
+                        _l.debug("Removed client from event subscribers")
+
+            client_socket.close()
+            _l.info(f"Client disconnected: {addr}")
+    
+    def _process_request(self, request: Dict[str, Any], client_socket: socket.socket = None) -> Any:
+        """Process a client request and return response"""
+        request_type = request.get("type")
+
+        if request_type == "subscribe_events":
+            # Client wants to subscribe to artifact change events
+            if self.server and client_socket:
+                with self.server._event_subscribers_lock:
+                    if client_socket not in self.server._event_subscribers:
+                        self.server._event_subscribers.append(client_socket)
+                        _l.info(f"Client subscribed to events (total subscribers: {len(self.server._event_subscribers)})")
+                return {"status": "subscribed"}
+            else:
+                return {"status": "error", "message": "Server not available"}
+
+        elif request_type == "unsubscribe_events":
+            # Client wants to unsubscribe from events
+            if self.server and client_socket:
+                with self.server._event_subscribers_lock:
+                    if client_socket in self.server._event_subscribers:
+                        self.server._event_subscribers.remove(client_socket)
+                        _l.info(f"Client unsubscribed from events (total subscribers: {len(self.server._event_subscribers)})")
+                return {"status": "unsubscribed"}
+            else:
+                return {"status": "error", "message": "Server not available"}
+
+        elif request_type == "server_info":
+            # Return the metadata cached by the server at init time. Reading
+            # ``deci.binary_hash`` or ``deci.binary_path`` here would re-enter
+            # the backend from a worker thread — which IDA/idalib rejects
+            # with "Function can be called from the main thread only".
+            if self.server is not None and self.server._cached_server_info is not None:
+                return dict(self.server._cached_server_info)
+            return {
+                "name": "DecLib DecompilerServer (AF_UNIX)",
+                "version": "3.0.0",
+                "decompiler": self.deci.name if self.deci else "unknown",
+                "protocol": "unix_socket",
+                "binary_hash": None,
+                "binary_path": None,
+                "server_id": self.server.server_id if self.server else None,
+            }
+
+        elif request_type == "get_light_artifacts":
+            collection_name = request.get("collection_name")
+            return self._get_light_artifacts(collection_name)
+
+        elif request_type == "get_full_artifact":
+            collection_name = request.get("collection_name")
+            key = request.get("key")
+
+            def _fetch_full_artifact():
+                collection = getattr(self.deci, collection_name)
+                return collection[key]
+
+            artifact = self._dispatch(_fetch_full_artifact)
+
+            # Serialize the full artifact safely
+            if hasattr(artifact, 'dumps') and hasattr(artifact, '__class__'):
+                try:
+                    return {
+                        'type': artifact.__class__.__name__,
+                        'module': artifact.__class__.__module__,
+                        'data': artifact.dumps(fmt=_WIRE_FMT),
+                        'is_artifact': True
+                    }
+                except Exception as e:
+                    _l.warning(f"Failed to serialize full artifact: {e}")
+                    # Fall back to direct return, which might fail with pickle
+                    return artifact
+            else:
+                return artifact
+
+        elif request_type == "method_call":
+            method_name = request.get("method_name")
+            args = request.get("args", [])
+            kwargs = request.get("kwargs", {})
+
+            # Handle dotted method names like "art_lifter.lift"
+            if "." in method_name:
+                obj = self.deci
+                for attr in method_name.split("."):
+                    obj = getattr(obj, attr)
+                method = obj
+            else:
+                # Get the method from the decompiler interface
+                method = getattr(self.deci, method_name)
+            result = self._dispatch(method, *args, **kwargs)
+            
+            # Check if result is an artifact and serialize it properly
+            if hasattr(result, 'dumps') and hasattr(result, '__class__'):
+                # This looks like an artifact, serialize it safely
+                try:
+                    return {
+                        'type': result.__class__.__name__,
+                        'module': result.__class__.__module__,
+                        'data': result.dumps(fmt=_WIRE_FMT),
+                        'is_artifact': True
+                    }
+                except Exception as e:
+                    _l.warning(f"Failed to serialize result artifact: {e}")
+                    # Fall back to direct return, which might fail with pickle
+                    return result
+            else:
+                # Not an artifact, return as-is
+                return result
+        
+        elif request_type == "property_get":
+            property_name = request.get("property_name")
+            return self._dispatch(lambda: getattr(self.deci, property_name))
+        
+        elif request_type == "shutdown_deci":
+            if self.deci and self.server is not None and not self.server._deci_shutdown_done:
+                # Route through the main-thread dispatcher for IDA — calling
+                # idapro.close_database() from a worker thread raises
+                # "Function can be called from the main thread only".
+                self._dispatch(self.deci.shutdown)
+                self.server._deci_shutdown_done = True
+            return {"status": "shutdown"}
+
+        elif request_type == "shutdown_server":
+            # Tear the server down asynchronously so we can still reply.
+            if self.server is not None:
+                threading.Thread(
+                    target=self.server.stop, name="declib-server-shutdown", daemon=True
+                ).start()
+            return {"status": "stopping"}
+        
+        else:
+            raise ValueError(f"Unknown request type: {request_type}")
+    
+    def _get_light_artifacts(self, collection_name: str) -> Dict:
+        """Get light artifacts for a collection, computing and caching on first request"""
+        with self._cache_lock:
+            cache_entry = self._light_caches.get(collection_name)
+
+            # Check if we have a valid cache entry
+            if cache_entry and time.time() - cache_entry["timestamp"] < self._cache_ttl:
+                return cache_entry["items"]
+
+            # Cache miss or stale - compute light artifacts on-demand
+            _l.debug(f"Computing light artifacts for {collection_name} on-demand")
+            try:
+                collection = getattr(self.deci, collection_name)
+                if hasattr(collection, '_lifted_art_lister'):
+                    start_time = time.time()
+                    light_items = self._dispatch(collection._lifted_art_lister)
+                    end_time = time.time()
+                    
+                    # Convert artifacts to serializable format using their own serialization
+                    serializable_items = {}
+                    for addr, artifact in light_items.items():
+                        try:
+                            # Use the artifact's built-in serialization which handles complex objects
+                            serialized = artifact.dumps(fmt=_WIRE_FMT)
+                            # Store as a tuple of (type_name, serialized_data) for reconstruction
+                            serializable_items[addr] = {
+                                'type': artifact.__class__.__name__,
+                                'module': artifact.__class__.__module__,
+                                'data': serialized
+                            }
+                        except Exception as e:
+                            _l.warning(f"Failed to serialize {artifact.__class__.__name__} at 0x{addr:x}: {e}")
+                            # Skip problematic artifacts rather than failing completely
+                            continue
+                    
+                    # Cache the serializable artifacts
+                    self._light_caches[collection_name] = {
+                        "items": serializable_items,
+                        "timestamp": time.time()
+                    }
+                    
+                    _l.info(f"Computed {len(serializable_items)} light {collection_name} in {end_time - start_time:.3f}s")
+                    return serializable_items
+                else:
+                    _l.warning(f"Collection {collection_name} does not support light artifacts")
+                    return {}
+                    
+            except Exception as e:
+                _l.warning(f"Failed to compute light artifacts for {collection_name}: {e}")
+                # Return stale cache if available, otherwise empty dict
+                if cache_entry:
+                    _l.debug(f"Returning stale cache for {collection_name} due to error")
+                    return cache_entry["items"]
+                return {}
+
+
+class DecompilerServer:
+    """
+    A server that exposes DecompilerInterface APIs over AF_UNIX sockets.
+    
+    This server wraps a DecompilerInterface instance and provides network access
+    to all its public methods and artifact collections through AF_UNIX sockets.
+    """
+    
+    def __init__(self,
+                 decompiler_interface: Optional[DecompilerInterface] = None,
+                 socket_path: Optional[str] = None,
+                 server_id: Optional[str] = None,
+                 register: bool = True,
+                 **interface_kwargs):
+        """
+        Initialize the DecompilerServer.
+
+        Args:
+            decompiler_interface: An existing DecompilerInterface instance. If None,
+                                one will be created using DecompilerInterface.discover()
+            socket_path: Path for the AF_UNIX socket. If None, a path is derived from server_id.
+            server_id:   Optional explicit server ID. If None, a new one is generated.
+            register:    If True, write the server info into the shared registry.
+            **interface_kwargs: Arguments passed to DecompilerInterface.discover() if
+                              decompiler_interface is None
+        """
+
+        self.server_id = server_id or server_registry.new_server_id()
+        self.socket_path = socket_path
+        self._register = register
+        self._registered = False
+        self._server_socket = None
+        self._server_thread = None
+        self._running = False
+        self._clients = []
+        self._client_threads = []
+
+        # Main-thread dispatch: some backends (notably IDA/idalib) reject
+        # cross-thread API access. For those we route backend calls through
+        # a queue so they run on the thread that set the backend up.
+        self._main_thread_queue: "queue.Queue" = queue.Queue()
+        self._main_thread_ident: Optional[int] = None
+
+        # Event subscription tracking
+        self._event_subscribers = []  # List of sockets subscribed to events
+        self._event_subscribers_lock = threading.Lock()
+
+        # Track whether deci.shutdown() already ran, so teardown is idempotent
+        # across the worker-initiated stop() and the main-thread __exit__.
+        self._deci_shutdown_done = False
+
+        # Initialize the decompiler interface
+        if decompiler_interface is not None:
+            self.deci = decompiler_interface
+        else:
+            if interface_kwargs and interface_kwargs.get("headless", False):
+                forced_decompiler = interface_kwargs.get("force_decompiler", None)
+                if forced_decompiler is None:
+                    _l.warning(f"Using a headless interface without setting a decompiler has unpredictable behavior!")
+                _l.info(f"Using headless interface utilizing %s", forced_decompiler)
+            else:
+                _l.info("Discovering decompiler interface...")
+
+            self.deci = DecompilerInterface.discover(**interface_kwargs)
+            if self.deci is None:
+                raise RuntimeError("Failed to discover decompiler interface")
+
+        # Cache static metadata on the *main* thread so that the connection
+        # handshake (`server_info`) never touches the backend from a worker
+        # thread — IDA/idalib raises "Function can be called from the main
+        # thread only" the moment such access happens.
+        self._cached_server_info = self._build_static_server_info()
+
+        # Create socket handler
+        self.handler = SocketServerHandler(self.deci, server=self)
+
+        # Register artifact change callbacks to broadcast events
+        self._register_artifact_callbacks()
+
+        # Generate socket path if not provided
+        if self.socket_path is None:
+            socket_path = server_registry.default_socket_path(self.server_id)
+            self.socket_path = socket_path
+            self._temp_dir = os.path.dirname(socket_path)
+        else:
+            self._temp_dir = None
+
+        _l.info(f"DecompilerServer initialized with {self.deci.name} interface (id={self.server_id})")
+        _l.info(f"Socket path: {self.socket_path}")
+
+    def _build_static_server_info(self) -> Dict[str, Any]:
+        """Collect immutable server metadata on whatever thread calls us.
+
+        This runs from ``__init__`` — i.e. the thread that constructed the
+        deci (the main thread in the CLI path). Capturing the values here
+        means ``server_info`` replies can be served from any worker thread
+        without re-entering backends like IDA that reject cross-thread API
+        calls.
+        """
+        binary_path = None
+        binary_hash = None
+        if self.deci:
+            try:
+                raw_path = self.deci.binary_path
+                binary_path = str(raw_path) if raw_path else None
+            except Exception as exc:
+                _l.debug("Failed to cache binary_path: %s", exc)
+            try:
+                binary_hash = self.deci.binary_hash
+            except Exception as exc:
+                _l.debug("Failed to cache binary_hash: %s", exc)
+
+        return {
+            "name": "DecLib DecompilerServer (AF_UNIX)",
+            "version": "3.0.0",
+            "decompiler": self.deci.name if self.deci else "unknown",
+            "protocol": "unix_socket",
+            "binary_hash": binary_hash,
+            "binary_path": binary_path,
+            "server_id": self.server_id,
+        }
+
+    def _register_artifact_callbacks(self):
+        """Register callbacks to broadcast artifact changes to subscribed clients"""
+        from declib.artifacts import Comment, Struct, Enum, Typedef, GlobalVariable, FunctionHeader, StackVariable
+
+        # Register callbacks for different artifact types
+        self.deci.artifact_change_callbacks[Comment].append(
+            lambda artifact, **kwargs: self._broadcast_event("comment_changed", artifact, **kwargs)
+        )
+        self.deci.artifact_change_callbacks[Struct].append(
+            lambda artifact, **kwargs: self._broadcast_event("struct_changed", artifact, **kwargs)
+        )
+        self.deci.artifact_change_callbacks[Enum].append(
+            lambda artifact, **kwargs: self._broadcast_event("enum_changed", artifact, **kwargs)
+        )
+        self.deci.artifact_change_callbacks[Typedef].append(
+            lambda artifact, **kwargs: self._broadcast_event("typedef_changed", artifact, **kwargs)
+        )
+        self.deci.artifact_change_callbacks[GlobalVariable].append(
+            lambda artifact, **kwargs: self._broadcast_event("global_variable_changed", artifact, **kwargs)
+        )
+        self.deci.artifact_change_callbacks[FunctionHeader].append(
+            lambda artifact, **kwargs: self._broadcast_event("function_header_changed", artifact, **kwargs)
+        )
+        self.deci.artifact_change_callbacks[StackVariable].append(
+            lambda artifact, **kwargs: self._broadcast_event("stack_variable_changed", artifact, **kwargs)
+        )
+
+    def _broadcast_event(self, event_type: str, artifact, **kwargs):
+        """Broadcast an artifact change event to all subscribed clients"""
+        with self._event_subscribers_lock:
+            if not self._event_subscribers:
+                _l.debug(f"No subscribers for event: {event_type}")
+                return
+
+            # Serialize the artifact
+            try:
+                serialized_artifact = {
+                    'type': artifact.__class__.__name__,
+                    'module': artifact.__class__.__module__,
+                    'data': artifact.dumps(fmt=_WIRE_FMT),
+                    'is_artifact': True
+                }
+
+                event_message = {
+                    "event_type": event_type,
+                    "artifact": serialized_artifact,
+                    "kwargs": kwargs
+                }
+
+                # Send to all subscribers
+                dead_subscribers = []
+                for subscriber_socket in self._event_subscribers:
+                    try:
+                        SocketProtocol.send_message(subscriber_socket, event_message)
+                        _l.debug(f"Broadcasted {event_type} to subscriber")
+                    except Exception as e:
+                        _l.warning(f"Failed to send event to subscriber: {e}")
+                        dead_subscribers.append(subscriber_socket)
+
+                # Remove dead subscribers
+                for dead_socket in dead_subscribers:
+                    self._event_subscribers.remove(dead_socket)
+                    _l.debug("Removed dead subscriber")
+
+            except Exception as e:
+                _l.error(f"Failed to broadcast event {event_type}: {e}")
+
+    def start(self):
+        """Start the server in a separate thread"""
+        if self._running:
+            _l.warning("Server is already running")
+            return
+        
+        _l.info(f"Starting DecompilerServer on {self.socket_path}")
+        
+        # Create socket (AF_UNIX if available, else AF_INET)
+        if hasattr(socket, "AF_UNIX"):
+            self._server_socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            self._server_socket.settimeout(1.0)
+            if os.path.exists(self.socket_path):
+                os.unlink(self.socket_path)
+            self._server_socket.bind(self.socket_path)
+        else:
+            self._server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self._server_socket.settimeout(1.0)
+            self._server_socket.bind(('127.0.0.1', 0))
+            port = self._server_socket.getsockname()[1]
+            try:
+                with open(self.socket_path, 'w') as f:
+                    f.write(str(port))
+            except Exception as e:
+                _l.error(f"Failed to write port to {self.socket_path}: {e}")
+        self._server_socket.listen(5)
+        
+        # Set running flag before starting thread
+        self._running = True
+
+        # Start server in a separate thread
+        self._server_thread = threading.Thread(target=self._server_loop, daemon=True)
+        self._server_thread.start()
+
+        # Register in shared registry so other processes can find us.
+        if self._register:
+            try:
+                binary_path = str(self.deci.binary_path) if self.deci and self.deci.binary_path else None
+                binary_hash = None
+                try:
+                    binary_hash = self.deci.binary_hash if self.deci else None
+                except Exception:
+                    binary_hash = None
+                server_registry.register_server({
+                    "id": self.server_id,
+                    "socket_path": self.socket_path,
+                    "backend": self.deci.name if self.deci else None,
+                    "binary_path": binary_path,
+                    "binary_hash": binary_hash,
+                })
+                self._registered = True
+            except Exception as exc:
+                _l.warning("Failed to register server: %s", exc)
+
+        _l.info(f"DecompilerServer started successfully on unix://{self.socket_path}")
+        _l.info("Connect with: DecompilerClient.discover('unix://{}')".format(self.socket_path))
+    
+    def _server_loop(self):
+        """Main server loop"""
+        try:
+            while self._running:
+                try:
+                    client_socket, addr = self._server_socket.accept()
+                    self._clients.append(client_socket)
+
+                    # Handle client in separate thread
+                    client_thread = threading.Thread(
+                        target=self.handler.handle_client,
+                        args=(client_socket, str(addr)),
+                        daemon=True
+                    )
+                    self._client_threads.append(client_thread)
+                    client_thread.start()
+
+                except socket.timeout:
+                    # Normal timeout, continue loop to check if we should stop
+                    continue
+                except OSError:
+                    # Socket was closed
+                    break
+                except Exception as e:
+                    _l.error(f"Error accepting client: {e}")
+
+        except Exception as e:
+            _l.error(f"Server loop error: {e}")
+        finally:
+            _l.info("Server loop ended")
+    
+    def stop(self):
+        """Stop the server"""
+        if not self._running:
+            _l.warning("Server is not running")
+            return
+        
+        _l.info("Stopping DecompilerServer...")
+        self._running = False
+
+        # Wake the main-thread dispatcher so it can exit `wait_for_shutdown`.
+        try:
+            self._main_thread_queue.put_nowait(_MAIN_THREAD_SHUTDOWN)
+        except Exception:
+            pass
+
+        # Close all client connections
+        for client in self._clients:
+            try:
+                client.close()
+            except:
+                pass
+        
+        # Close server socket
+        if self._server_socket:
+            self._server_socket.close()
+        
+        # Wait for threads to finish (short timeout since we use daemon threads)
+        if self._server_thread and self._server_thread.is_alive():
+            self._server_thread.join(timeout=2.0)
+
+        for thread in self._client_threads:
+            if thread.is_alive():
+                thread.join(timeout=0.5)
+        
+        # Clean up socket file and temp directory
+        if os.path.exists(self.socket_path):
+            os.unlink(self.socket_path)
+
+        if self._temp_dir and os.path.exists(self._temp_dir):
+            try:
+                os.rmdir(self._temp_dir)
+            except:
+                pass
+
+        # Remove from registry
+        if self._registered:
+            try:
+                server_registry.unregister_server(self.server_id)
+            except Exception as exc:
+                _l.debug("Failed to unregister server %s: %s", self.server_id, exc)
+            self._registered = False
+
+        # Shutdown the decompiler interface. For backends that need the main
+        # thread (IDA/idalib), defer to the main thread which will run the
+        # shutdown after leaving the dispatch loop — doing it from a worker
+        # thread here raises "Function can be called from the main thread
+        # only". wait_for_shutdown() / __exit__ pick it up via
+        # _shutdown_deci_if_needed().
+        if self.deci and not self._deci_shutdown_done:
+            on_main = (
+                self._main_thread_ident is None
+                or threading.get_ident() == self._main_thread_ident
+            )
+            if on_main or not self.requires_main_thread:
+                try:
+                    self.deci.shutdown()
+                    self._deci_shutdown_done = True
+                except Exception as e:
+                    _l.warning(f"Error shutting down decompiler: {e}")
+
+        _l.info("DecompilerServer stopped")
+    
+    def is_running(self) -> bool:
+        """Check if the server is currently running"""
+        return self._running
+
+    @property
+    def requires_main_thread(self) -> bool:
+        """Whether backend API calls must be routed to the main thread.
+
+        Set by the decompiler interface; IDA's idalib is the canonical case.
+        """
+        if not self.deci:
+            return False
+        return bool(getattr(self.deci, "requires_main_thread_dispatch", False))
+
+    def run_on_main_thread(self, func, *args, **kwargs):
+        """Run ``func(*args, **kwargs)`` on the server's main thread.
+
+        If the calling thread *is* the main thread, execute inline — this
+        avoids a deadlock when the main thread is itself invoking a method
+        (e.g. during ``__enter__`` / ``start``).
+        """
+        if self._main_thread_ident is not None and threading.get_ident() == self._main_thread_ident:
+            return func(*args, **kwargs)
+
+        result_q: "queue.Queue" = queue.Queue(maxsize=1)
+        self._main_thread_queue.put((func, args, kwargs, result_q))
+        result = result_q.get()
+        if isinstance(result, _MainThreadError):
+            raise result.exc
+        return result
+
+    def _main_thread_dispatch_loop(self):
+        """Drain backend work from the main-thread queue until shutdown.
+
+        Only used for backends that require main-thread dispatch (IDA).
+        Runs on the thread that called ``wait_for_shutdown`` — i.e. the
+        thread that originally created the ``deci``.
+        """
+        self._main_thread_ident = threading.get_ident()
+        while self._running:
+            try:
+                item = self._main_thread_queue.get(timeout=0.25)
+            except queue.Empty:
+                continue
+            if item is _MAIN_THREAD_SHUTDOWN:
+                break
+            func, args, kwargs, result_q = item
+            try:
+                result = func(*args, **kwargs)
+            except BaseException as exc:  # relay every failure, including Java exceptions
+                result = _MainThreadError(exc)
+            result_q.put(result)
+
+    def wait_for_shutdown(self):
+        """Wait for the server to be shut down (blocking)"""
+        if self.requires_main_thread:
+            # Become the main-thread dispatcher. This blocks until stop().
+            try:
+                self._main_thread_dispatch_loop()
+            except KeyboardInterrupt:
+                _l.info("Received interrupt signal, stopping server...")
+                self.stop()
+            # Now that we're back on the main thread with the dispatch loop
+            # drained, finish any backend teardown stop() had to defer.
+            self._shutdown_deci_if_needed()
+            return
+
+        if self._server_thread and self._server_thread.is_alive():
+            try:
+                self._server_thread.join()
+            except KeyboardInterrupt:
+                _l.info("Received interrupt signal, stopping server...")
+                self.stop()
+
+    def _shutdown_deci_if_needed(self):
+        """Run deci.shutdown() once, from the caller's thread.
+
+        Callers must ensure they are on the thread that owns the backend
+        (typically the main thread). Idempotent.
+        """
+        if not self.deci or self._deci_shutdown_done:
+            return
+        try:
+            self.deci.shutdown()
+        except Exception as e:
+            _l.warning(f"Error shutting down decompiler: {e}")
+        finally:
+            self._deci_shutdown_done = True
+
+    def __enter__(self):
+        """Context manager entry"""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.stop()
+        self._shutdown_deci_if_needed()