matlab-proxy 0.5.3__py3-none-any.whl → 0.30.1__py3-none-any.whl

matlab_proxy_manager/utils/helpers.py

@@ -0,0 +1,314 @@
+# Copyright 2024-2025 The MathWorks, Inc.
+import asyncio
+import http
+import os
+import socket
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Dict, Generator, Optional, Tuple
+from urllib.parse import urlparse
+
+import psutil
+import requests
+from aiohttp import web
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from matlab_proxy import settings
+from matlab_proxy_manager.storage.file_repository import FileRepository
+from matlab_proxy_manager.utils import logger
+
+log = logger.get()
+
+
+def is_server_ready(url: Optional[str], retries: int = 2, backoff_factor=None) -> bool:
+    """
+    Check if the server at the given URL is ready.
+
+    Args:
+        url (str): The URL of the server.
+
+    Returns:
+        bool: True if the server is ready, False otherwise.
+    """
+    try:
+        # Validate URL
+        parsed_url = urlparse(url)
+        if not all([parsed_url.scheme, parsed_url.netloc]):
+            log.debug("Invalid URL provided: %s", url)
+            return False
+
+        matlab_proxy_index_page_identifier = "MWI_MATLAB_PROXY_IDENTIFIER"
+        resp = requests_retry_session(
+            retries=retries, backoff_factor=backoff_factor
+        ).get(f"{url}", verify=False)
+        log.debug("Response status code from server readiness: %s", resp.status_code)
+        return (
+            resp.status_code == http.HTTPStatus.OK
+            and matlab_proxy_index_page_identifier in resp.text
+        )
+    except Exception as e:
+        log.debug("Couldn't reach the server with error: %s", e)
+        return False
+
+
+def requests_retry_session(
+    retries=3, backoff_factor=0.1, session=None
+) -> requests.Session:
+    """
+    Create a requests session with retry logic.
+
+    Args:
+        retries (int): The number of retries.
+        backoff_factor (float): The backoff factor for retries.
+        session (requests.Session, optional): An existing requests session.
+
+    Returns:
+        requests.Session: The requests session with retry logic.
+    """
+    session = session or requests.session()
+    retry = Retry(
+        total=retries,
+        read=retries,
+        connect=retries,
+        backoff_factor=backoff_factor,
+        allowed_methods=frozenset(["DELETE", "GET", "POST"]),
+    )
+    adapter = HTTPAdapter(max_retries=retry)
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+    return session
+
+
+def does_process_exist(pid: Optional[str]) -> bool:
+    """
+    Checks if the parent process is alive.
+
+    Returns:
+        bool: True if the parent process is alive, False otherwise.
+    """
+    return bool(pid and psutil.pid_exists(int(pid)))
+
+
+def convert_mwi_env_vars_to_header_format(
+    env_vars: Dict[str, str], prefix: str
+) -> Dict[str, str]:
+    """
+    Parse and transform environment variables with a specific prefix.
+
+    Args:
+        env_vars (dict): The environment variables.
+        prefix (str): The prefix to filter the environment variables.
+
+    Returns:
+        dict: The transformed environment variables.
+    """
+    return {
+        key.replace("_", "-"): value
+        for key, value in env_vars.items()
+        if key.startswith(prefix)
+    }
+
+
+def create_and_get_proxy_manager_data_dir() -> Path:
+    """
+    Create and get the proxy manager data directory.
+
+    Returns:
+        Path: The path to the proxy manager data directory.
+    """
+
+    config_dir = settings.get_mwi_config_folder(dev=False)
+    data_dir = Path(config_dir, "proxy_manager")
+    Path.mkdir(data_dir, parents=True, exist_ok=True)
+    return data_dir
+
+
+async def delete_dangling_servers(app: web.Application) -> None:
+    """
+    Delete dangling matlab proxy servers that are no longer alive.
+
+    Args:
+        app (web.Application): aiohttp web application
+    """
+    is_delete_successful = _are_orphaned_servers_deleted()
+    log.debug("Deleted dangling matlab proxy servers: %s", is_delete_successful)
+
+
+def _are_orphaned_servers_deleted(predicate: Optional[str] = "") -> bool:
+    """
+    Get all the files under the proxy manager directory, check the status of the servers,
+    and delete orphaned servers and their corresponding files.
+
+    - Checks if the parent PID of each server is still alive. If not, sends a SIGKILL
+    to the server and deletes the corresponding file.
+    - Checks if the servers in those files are still alive by sending GET requests to
+    their absolute URLs. If not, deletes the corresponding file.
+
+    Returns:
+        bool: True if any server was deleted, False otherwise.
+    """
+    data_dir = create_and_get_proxy_manager_data_dir()
+    storage = FileRepository(data_dir)
+    servers: dict = storage.get_all()
+
+    def _matches_predicate(filename: str) -> bool:
+        return filename.split("_")[0] == str(predicate)
+
+    # Checks only a subset of servers (that matches the parent_pid of the caller)
+    # to reduce the MATLAB proxy startup time
+    if predicate:
+        servers = {
+            filename: server
+            for filename, server in servers.items()
+            if _matches_predicate(Path(filename).stem)
+        }
+        if not servers:
+            log.debug("Parent pid not matched, nothing to cleanup")
+            return True
+
+    return _delete_server_and_file(storage, servers)
+
+
+def _delete_server_and_file(storage, servers) -> bool:
+    is_server_deleted = False
+    for filename, server in servers.items():
+        if not server.is_server_alive():
+            log.debug("Server is not alive, cleaning up files")
+            try:
+                storage.delete(os.path.basename(filename))
+            except Exception as ex:
+                log.debug("Failed to delete file: %s", ex)
+            is_server_deleted = True
+        elif not does_process_exist(server.parent_pid):
+            log.debug("Server's parent is gone, shutting down matlab proxy")
+            try:
+                server.shutdown()
+            except Exception as ex:
+                log.debug("Failed to shutdown the matlab proxy server: %s", ex)
+            finally:
+                # Ensures files are cleaned up even if shutdown fails
+                storage.delete(os.path.basename(filename))
+                is_server_deleted = True
+
+    return is_server_deleted
+
+
+async def poll_for_server_deletion(app: web.Application) -> None:
+    """
+    Poll for server deletion for a specified timeout period.
+
+    This function continuously checks if orphaned servers are deleted within a
+    specified timeout period. If servers are deleted, it breaks out of the loop.
+
+    Logs the status of server deletion attempts.
+    """
+    timeout_in_seconds: int = 2
+    log.debug("Interrupt/termination signal caught, cleaning up resources")
+    start_time = time.time()
+
+    try:
+        while time.time() - start_time < timeout_in_seconds:
+            is_server_deleted = _are_orphaned_servers_deleted()
+            if is_server_deleted:
+                log.debug("Servers deleted, breaking out of loop")
+                break
+            log.debug("Servers not deleted, waiting")
+            # Sleep for a short interval before polling again
+            await asyncio.sleep(0.5)
+    except Exception as ex:
+        log.debug("Error while polling for server deletion: %s", ex)
+
+
+@contextmanager
+def find_free_port() -> Generator[Tuple[str, socket.socket], None, None]:
+    """
+    Context manager for finding a free port on the system.
+
+    This function creates a socket, binds it to an available port, and yields
+    the port number along with the socket object. The socket is automatically
+    closed when exiting the context.
+
+    Yields:
+        Tuple[str, socket.socket]: A tuple containing:
+            - str: The free port number as a string.
+            - socket.socket: The socket object.
+    """
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.bind(("", 0))
+    port = str(s.getsockname()[1])
+    try:
+        yield port, s
+    finally:
+        try:
+            s.close()
+        except OSError as ex:
+            # Socket already closed, log and ignore the exception
+            log.debug("Failed to close socket: %s", ex)
+
+
+def pre_load_from_state_file(data_dir: str) -> Dict[str, str]:
+    """
+    Pre-load server states from the state files in the specified data directory.
+
+    Args:
+        data_dir (Path): The directory containing the state files.
+
+    Returns:
+        Dict[str, Dict]: A dictionary with server IDs as keys and server states as values.
+    """
+    storage = FileRepository(data_dir)
+    servers = storage.get_all()
+    return {server.id: server.as_dict() for server in servers.values()}
+
+
+def is_only_reference(file_path: str) -> bool:
+    """
+    Check if the specified file is the only file in its directory.
+
+    Args:
+        file_path (str): The path to the file.
+
+    Returns:
+        bool: True if the file is the only file in its directory, False otherwise.
+    """
+    parent_dir = Path(file_path).parent.absolute()
+    files = os.listdir(parent_dir)
+    return len(files) == 1 and files[0] == os.path.basename(file_path)
+
+
+def create_state_file(data_dir, server_process, filename: str):
+    """
+    Create a state file in the specified data directory.
+
+    This function creates a state file for the given server process in the specified
+    data directory. It logs the process and handles any exceptions that might occur.
+
+    Args:
+        data_dir: The directory where the state file will be created.
+        server_process (ServerProcess): The server process for which the state file is created.
+        filename (str): The name of the state file to be created.
+
+    Raises:
+        IOError: If there is an error creating the state file or adding the server
+        process to the repository.
+    """
+    try:
+        storage = FileRepository(data_dir)
+        storage.add(server=server_process, filename=filename)
+        log.debug("State file %s created in %s", filename, data_dir)
+    except Exception as e:
+        log.error(
+            "Failed to create state file %s in %s, error: %s", filename, data_dir, e
+        )
+        raise IOError(
+            f"Failed to create state file {filename} in {data_dir}, error: {e}"
+        ) from e
+
+
+def render_error_page(error_msg: str) -> web.Response:
+    """Returns 503 with error text"""
+    return web.HTTPServiceUnavailable(
+        text=f'<p style="color: red;">{error_msg}</p>', content_type="text/html"
+    )

matlab_proxy_manager/utils/logger.py

@@ -0,0 +1,76 @@
+# Copyright 2024-2025 The MathWorks, Inc.
+# Helper functions to access & control the logging behavior of the app
+
+import logging
+import os
+
+
+# TODO: Consolidate all logging setup into a common module (MATLABProxy, MATLABKernel, MATLABProxyManager)
+def get(init=False):
+    """Get the logger used by this application.
+        Set init=True to initialize the logger
+    Returns:
+        Logger: The logger used by this application.
+    """
+    if init is True:
+        return __set_logging_configuration()
+
+    return __get_mw_logger()
+
+
+def __get_mw_logger_name():
+    """Name of logger used by the app
+
+    Returns:
+        String: The name of the Logger.
+    """
+    return "MATLABProxyManager"
+
+
+def __get_mw_logger():
+    """Returns logger for use in this app.
+
+    Returns:
+        Logger: A logger object
+    """
+    return logging.getLogger(__get_mw_logger_name())
+
+
+def __set_logging_configuration():
+    """Sets the logging environment for the app
+
+    Returns:
+        Logger: Logger object with the set configuration.
+    """
+    # query for user specified environment variables
+    log_level = os.getenv(__get_env_name_logging_level(), __get_default_log_level())
+
+    ## Set logging object
+    logger = __get_mw_logger()
+
+    # log_level is either set by environment or is the default value.
+    logger.info("Initializing logger with log_level: %s", log_level)
+    logger.setLevel(log_level)
+
+    # Allow other libraries used by this integration to
+    # also print their logs at the specified level
+    logging.basicConfig(level=log_level)
+
+    # Suppress debug logs from the watchdog module
+    logging.getLogger("watchdog").setLevel(logging.WARNING)
+
+    return logger
+
+
+def __get_env_name_logging_level():
+    """Specifies the logging level used by app's loggers"""
+    return "MWI_MPM_LOG_LEVEL"
+
+
+def __get_default_log_level():
+    """The default logging level used by this application.
+
+    Returns:
+        String: The default logging level
+    """
+    return "INFO"

matlab_proxy_manager/web/README.md

@@ -0,0 +1,37 @@
+# MATLAB Proxy Manager - Web
+
+This README is intended for MathWorks® developers only.
+The web module is an important component of the matlab-proxy-manager, responsible for initiating the proxy manager in process mode. This module is specifically designed to be utilized within the Jupyter ecosystem, facilitating seamless integration with Jupyter Server Proxy.
+
+## Key Features
+### Process Mode Execution:
+
+The web module contains the code necessary to start the MATLAB proxy manager in process mode. This mode is essential for managing MATLAB sessions within a Jupyter environment, allowing users to interact with MATLAB through a web-based interface.
+
+### Integration with Jupyter Server Proxy:
+
+The web module is accessed exclusively by the Jupyter Server Proxy. It ensures that MATLAB can be launched and managed effectively as part of a Jupyter session, providing a seamless user experience.
+
+### Environment Variable Configuration:
+
+The web module relies on three critical environment variables to function correctly:
+1. MWI_MPM_PORT: Specifies the port on which the proxy manager should start. This allows for flexible configuration and ensures that the proxy manager can be accessed on the appropriate network endpoint.
+2. MWI_MPM_AUTH_TOKEN: Used for secure communication between the Jupyter Server Proxy and the proxy manager. This token ensures that only authorized requests can interact with the proxy manager, enhancing security.
+3. MWI_MPM_PARENT_PID: Provides context for the process, allowing resources to be filtered based on their originating parent process. This is particularly useful for distinguishing resources started by different Jupyter servers.
+
+### Support for Proxy Workflow:
+
+The web module supports the proxy workflow, which is activated when the MATLAB Web Desktop is launched. This workflow ensures that users can access MATLAB's graphical interface through their web browser, maintaining a consistent and interactive experience.
+
+## Usage
+The web module is typically invoked by the Jupyter Server Proxy and does not require direct interaction from end-users. However, it is essential to ensure that the necessary environment variables are correctly set before launching the module.
+
+## Design Considerations
+1. Security: The use of an authentication token ensures secure communication between components, preventing unauthorized access.
+2. Flexibility: By leveraging environment variables, the web module can be easily configured to meet the specific needs of different deployment environments.
+
+---
+
+Copyright 2024 The MathWorks, Inc.
+
+---

matlab_proxy_manager/web/__init__.py

@@ -0,0 +1 @@
+# Copyright 2024 The MathWorks, Inc.