matlab-proxy 0.25.0__py3-none-any.whl → 0.26.0__py3-none-any.whl

matlab_proxy_manager/lib/api.py

@@ -3,13 +3,14 @@ import asyncio
 import os
 import secrets
 import subprocess
-from typing import List, Optional, Tuple
+from typing import List, Tuple
 
 import matlab_proxy
+import matlab_proxy.util.mwi.environment_variables as mwi_env
 import matlab_proxy.util.system as mwi_sys
 from matlab_proxy_manager.storage.file_repository import FileRepository
 from matlab_proxy_manager.storage.server import ServerProcess
-from matlab_proxy_manager.utils import constants, helpers, logger
+from matlab_proxy_manager.utils import constants, exceptions, helpers, logger
 
 # Used to list all the public-facing APIs exported by this module.
 __all__ = ["shutdown", "start_matlab_proxy_for_kernel", "start_matlab_proxy_for_jsp"]
@@ -20,7 +21,7 @@ log = logger.get(init=True)
 
 
 async def start_matlab_proxy_for_kernel(
-    caller_id: str, parent_id: str, is_shared_matlab: bool
+    caller_id: str, parent_id: str, is_shared_matlab: bool, base_url_prefix: str = ""
 ):
     """
     Starts a MATLAB proxy server specifically for MATLAB Kernel.
@@ -29,12 +30,18 @@ async def start_matlab_proxy_for_kernel(
     set to None, for starting the MATLAB proxy server via proxy manager.
     """
     return await _start_matlab_proxy(
-        caller_id=caller_id, ctx=parent_id, is_shared_matlab=is_shared_matlab
+        caller_id=caller_id,
+        ctx=parent_id,
+        is_shared_matlab=is_shared_matlab,
+        base_url_prefix=base_url_prefix,
     )
 
 
 async def start_matlab_proxy_for_jsp(
-    parent_id: str, is_shared_matlab: bool, mpm_auth_token: str
+    parent_id: str,
+    is_shared_matlab: bool,
+    mpm_auth_token: str,
+    base_url_prefix: str = "",
 ):
     """
     Starts a MATLAB proxy server specifically for Jupyter Server Proxy (JSP) - Open MATLAB launcher.
@@ -47,120 +54,136 @@ async def start_matlab_proxy_for_jsp(
         ctx=parent_id,
         is_shared_matlab=is_shared_matlab,
         mpm_auth_token=mpm_auth_token,
+        base_url_prefix=base_url_prefix,
     )
 
 
-async def _start_matlab_proxy(**options) -> Optional[dict]:
+async def _start_matlab_proxy(**options) -> dict:
     """
-    Start a MATLAB proxy server.
+    Starts a MATLAB proxy server with the specified options.
 
-    This function starts a MATLAB proxy server based on the provided context and caller ID.
-    It handles the creation of new servers and the reuse of existing ones.
+    This function validates the provided options, checks for existing server instances,
+    and either returns an existing server process or starts a new MATLAB proxy server.
+    It ensures that required arguments are present, handles token generation, and manages
+    server readiness and error handling.
 
-    Args (keyword arguments):
-        - caller_id (str): The identifier for the caller (kernel id for kernels, "jsp" for JSP).
-        - ctx (str): The context in which the server is being started (parent pid).
-        - is_shared_matlab (bool, optional): Whether to start a shared MATLAB proxy instance.
-        Defaults to False.
-        - mpm_auth_token (str, optional): The MATLAB proxy manager token. If not provided,
-        a new token is generated. Defaults to None.
+    Args:
+        **options: Arbitrary keyword arguments containing the following keys:
+            - caller_id (str): The identifier for the caller (kernel id for kernels, "jsp" for JSP).
+            - ctx (str): The context in which the server is being started (parent pid).
+            - is_shared_matlab (bool): Flag indicating if the MATLAB proxy is shared.
+            - mpm_auth_token (Optional[str]): Authentication token for the MATLAB proxy manager.
+            - base_url_prefix (Optional[str]): Custom URL path which gets added to mwi_base_url
 
     Returns:
-        ServerProcess: The process representing the MATLAB proxy server.
+        dict: A dictionary representation of the server process, including any errors encountered.
 
     Raises:
         ValueError: If `caller_id` is "default" and `is_shared_matlab` is False.
     """
-    # Validate arguments
-    required_args: List[str] = ["caller_id", "ctx", "is_shared_matlab"]
-    missing_args: List[str] = [arg for arg in required_args if arg not in options]
-
-    if missing_args:
-        raise ValueError(f"Missing required arguments: {', '.join(missing_args)}")
+    _validate_required_arguments(options)
 
     caller_id: str = options["caller_id"]
     ctx: str = options["ctx"]
     is_shared_matlab: bool = options.get("is_shared_matlab", True)
-    mpm_auth_token: Optional[str] = options.get("mpm_auth_token", None)
+    mpm_auth_token = options.get("mpm_auth_token", None) or secrets.token_hex(32)
 
     if not is_shared_matlab and caller_id == "default":
         raise ValueError(
             "Caller id cannot be default when matlab proxy is not shareable"
         )
 
-    mpm_auth_token = mpm_auth_token or secrets.token_hex(32)
-
     # Cleanup stale entries before starting new instance of matlab proxy server
     helpers._are_orphaned_servers_deleted(ctx)
 
-    ident = caller_id if not is_shared_matlab else "default"
-    key = f"{ctx}_{ident}"
-    log.debug("Starting matlab proxy using %s, %s, %s", ctx, ident, is_shared_matlab)
-
-    data_dir = helpers.create_and_get_proxy_manager_data_dir()
-    server_process = ServerProcess.find_existing_server(data_dir, key)
+    client_id = caller_id if not is_shared_matlab else "default"
+    matlab_session_dir = f"{ctx}_{client_id}"
+    filename = f"{ctx}_{caller_id}"
+    proxy_manager_root_dir = helpers.create_and_get_proxy_manager_data_dir()
+    existing_matlab_proxy_process = ServerProcess.find_existing_server(
+        proxy_manager_root_dir, matlab_session_dir
+    )
 
-    if server_process:
+    if existing_matlab_proxy_process:
         log.debug("Found existing server for aliasing")
 
         # Create a backend file for this caller for reference tracking
-        helpers.create_state_file(data_dir, server_process, f"{ctx}_{caller_id}")
+        helpers.create_state_file(
+            proxy_manager_root_dir, existing_matlab_proxy_process, filename
+        )
+
+        return existing_matlab_proxy_process.as_dict()
 
     # Create a new matlab proxy server
-    else:
-        server_process = await _start_subprocess_and_check_for_readiness(
-            ident, ctx, key, is_shared_matlab, mpm_auth_token
+    try:
+        base_url_prefix = options.get("base_url_prefix", "")
+
+        # Prepare matlab proxy command and required environment variables
+        matlab_proxy_cmd, matlab_proxy_env = _prepare_cmd_and_env_for_matlab_proxy(
+            client_id, base_url_prefix
         )
 
+        log.debug(
+            "Starting new matlab proxy server using ctx=%s, client_id=%s, is_shared_matlab=%s",
+            ctx,
+            client_id,
+            is_shared_matlab,
+        )
+        # Start the matlab proxy process
+        process_id, url = await _start_subprocess(matlab_proxy_cmd, matlab_proxy_env)
+        log.debug("MATLAB proxy process url: %s", url)
+
+        matlab_proxy_process = ServerProcess(
+            server_url=url,
+            mwi_base_url=matlab_proxy_env.get(mwi_env.get_env_name_base_url()),
+            headers=helpers.convert_mwi_env_vars_to_header_format(
+                matlab_proxy_env, "MWI"
+            ),
+            pid=str(process_id),
+            parent_pid=ctx,
+            id=matlab_session_dir,
+            type="shared" if is_shared_matlab else "isolated",
+            mpm_auth_token=mpm_auth_token,
+        )
+
+        await _check_for_process_readiness(matlab_proxy_process)
+
         # Store the newly created server into filesystem
-        if server_process:
-            helpers.create_state_file(data_dir, server_process, f"{ctx}_{caller_id}")
+        helpers.create_state_file(
+            proxy_manager_root_dir, matlab_proxy_process, filename
+        )
+        return matlab_proxy_process.as_dict()
 
-    return server_process.as_dict() if server_process else None
+    # Return a server process instance with the errors information set
+    except exceptions.ProcessStartError as pse:
+        return ServerProcess(errors=[str(pse)]).as_dict()
+    except exceptions.ServerReadinessError as sre:
+        return ServerProcess(errors=[str(sre)]).as_dict()
+    except Exception as e:
+        log.error("Error starting matlab proxy server: %s", str(e))
+        return ServerProcess(errors=[str(e)]).as_dict()
 
 
-async def _start_subprocess_and_check_for_readiness(
-    server_id: str, ctx: str, key: str, is_shared_matlab: bool, mpm_auth_token: str
-) -> Optional[ServerProcess]:
-    """
-    Starts a MATLAB proxy server.
+def _validate_required_arguments(options):
+    # Validates that all required arguments are present in the supplied values
+    required_args: List[str] = ["caller_id", "ctx", "is_shared_matlab"]
+    missing_args: List[str] = [arg for arg in required_args if arg not in options]
 
-    This function performs the following steps:
-    1. Prepares the command and environment variables required to start the MATLAB proxy server.
-    2. Initializes the MATLAB proxy process.
-    3. Checks if the MATLAB proxy server is ready.
-    4. Creates and returns a ServerProcess instance if the server is ready.
+    if missing_args:
+        raise ValueError(f"Missing required arguments: {', '.join(missing_args)}")
 
-    Returns:
-        Optional[ServerProcess]: An instance of ServerProcess if the server is successfully started,
-        otherwise None.
+
+async def _check_for_process_readiness(matlab_proxy_process: ServerProcess):
     """
-    log.debug("Starting new matlab proxy server")
-
-    # Prepare matlab proxy command and required environment variables
-    matlab_proxy_cmd, matlab_proxy_env = _prepare_cmd_and_env_for_matlab_proxy()
-
-    # Start the matlab proxy process
-    result = await _start_subprocess(matlab_proxy_cmd, matlab_proxy_env, server_id)
-    if not result:
-        log.error("Could not start matlab proxy")
-        return None
-
-    process_id, url, mwi_base_url = result
-
-    log.debug("Matlab proxy process info: %s, %s", url, mwi_base_url)
-    matlab_proxy_process = ServerProcess(
-        server_url=url,
-        mwi_base_url=mwi_base_url,
-        headers=helpers.convert_mwi_env_vars_to_header_format(matlab_proxy_env, "MWI"),
-        pid=str(process_id),
-        parent_pid=ctx,
-        id=key,
-        type="shared" if is_shared_matlab else "named",
-        mpm_auth_token=mpm_auth_token,
-    )
+    Checks if the MATLAB proxy server is ready.
 
-    # Check for the matlab proxy server readiness
+    Args:
+        matlab_proxy_process (ServerProcess): Deserialized matlab-proxy process
+
+    Raises:
+        ServerReadinessError: If the MATLAB proxy server is not ready after retries.
+    """
+    # Check for the matlab proxy server readiness - with retries
     if not helpers.is_server_ready(
         url=matlab_proxy_process.absolute_url, retries=7, backoff_factor=0.5
     ):
@@ -168,19 +191,21 @@ async def _start_subprocess_and_check_for_readiness(
             "MATLAB Proxy Server unavailable: matlab-proxy-app failed to start or has timed out."
         )
         matlab_proxy_process.shutdown()
-        matlab_proxy_process = None
-
-    return matlab_proxy_process
+        raise exceptions.ServerReadinessError()
 
 
-def _prepare_cmd_and_env_for_matlab_proxy():
+def _prepare_cmd_and_env_for_matlab_proxy(client_id: str, base_url_prefix: str):
     """
     Prepare the command and environment variables for starting the MATLAB proxy.
 
     Returns:
         Tuple: A tuple containing the MATLAB proxy command and environment variables.
     """
-    from jupyter_matlab_proxy import config
+    # Get config from matlab_proxy module if jupyter_matlab_proxy module is not available
+    try:
+        from jupyter_matlab_proxy import config
+    except ImportError:
+        from matlab_proxy.default_configuration import config
 
     # Get the command to start matlab-proxy
     matlab_proxy_cmd: list = [
@@ -189,8 +214,12 @@ def _prepare_cmd_and_env_for_matlab_proxy():
         config.get("extension_name"),
     ]
 
+    mwi_base_url = _construct_mwi_base_url(base_url_prefix, client_id)
+    log.info("MWI_BASE_URL : %s", mwi_base_url)
+
     input_env: dict = {
         "MWI_AUTH_TOKEN": secrets.token_urlsafe(32),
+        "MWI_BASE_URL": mwi_base_url,
     }
 
     matlab_proxy_env: dict = os.environ.copy()
@@ -199,37 +228,55 @@ def _prepare_cmd_and_env_for_matlab_proxy():
     return matlab_proxy_cmd, matlab_proxy_env
 
 
-async def _start_subprocess(cmd, env, server_id) -> Optional[Tuple[int, str, str]]:
+def _construct_mwi_base_url(base_url_prefix: str, client_id: str):
+    # Converts to correct base url (e.g. /jupyter/, default to /jupyter/matlab/default)
+    log.debug(
+        "base_url_prefix_from_client: %s, client_id: %s", base_url_prefix, client_id
+    )
+
+    if base_url_prefix:
+        base_url_prefix = base_url_prefix.rstrip("/")
+    prefix = constants.MWI_BASE_URL_PREFIX.strip("/")
+    client_id = client_id.strip("/")
+    return "/".join([base_url_prefix, prefix, client_id])
+
+
+async def _start_subprocess(cmd: list, env: dict) -> Tuple[int, str]:
     """
     Initializes and starts a subprocess using the specified command and provided environment.
 
+    Args:
+        cmd (list): The command to execute the subprocess.
+        env (dict): The environment variables to set for the subprocess.
+
     Returns:
-        Optional[int]: The process ID if the process is successfully created, otherwise None.
+        Optional[Tuple[int, str]]: A tuple containing the process ID, the URL
+        of the server, or None if the process fails to start.
     """
+
     process = None
-    mwi_base_url: str = f"{constants.MWI_BASE_URL_PREFIX}{server_id}"
+    url = None
 
     # Get a free port and corresponding bound socket
     with helpers.find_free_port() as (port, _):
+        log.debug("Allocated port %s", port)
+
         env.update(
             {
                 "MWI_APP_PORT": port,
-                "MWI_BASE_URL": mwi_base_url,
             }
         )
 
         # Using loopback address so that DNS resolution doesn't add latency in Windows
-        url: str = f"http://127.0.0.1:{port}"
-
+        url = f"http://127.0.0.1:{port}"
         process = await _initialize_process_based_on_os_type(cmd, env)
-
-    if not process:
-        log.error("Matlab proxy process not created due to some error")
-        return None
-
-    process_pid = process.pid
-    log.debug("MATLAB proxy info: pid = %s, rc = %s", process_pid, process.returncode)
-    return process_pid, url, mwi_base_url
+        process_pid = process.pid
+        log.debug(
+            "MATLAB proxy info: pid = %s, returncode = %s",
+            process_pid,
+            process.returncode,
+        )
+        return process_pid, url
 
 
 async def _initialize_process_based_on_os_type(cmd, env):
@@ -240,19 +287,18 @@ async def _initialize_process_based_on_os_type(cmd, env):
     environment variables. It handles both POSIX and Windows systems differently.
 
     Args:
-        cmd (List[str]): The command to execute in the subprocess.
-        env (Dict[str, str]): The environment variables for the subprocess.
+        cmd (list): The command to execute the subprocess.
+        env (dict): The environment variables to set for the subprocess.
 
     Returns:
-        Union[Process, None, Popen[bytes]]: The created subprocess object if successful,
-        or None if an error occurs during subprocess creation.
+        subprocess.Popen or asyncio.subprocess.Process: The process object for the started subprocess.
 
     Raises:
-        Exception: If there's an error creating the subprocess (caught and logged).
+        exceptions.ProcessStartError: If the subprocess fails to start.
     """
-    if mwi_sys.is_posix():
-        log.debug("Starting matlab proxy subprocess for posix")
-        try:
+    try:
+        if mwi_sys.is_posix():
+            log.debug("Starting matlab proxy subprocess for posix")
             return await asyncio.create_subprocess_exec(
                 *cmd,
                 env=env,
@@ -262,19 +308,15 @@ async def _initialize_process_based_on_os_type(cmd, env):
                 # https://github.com/ipython/ipykernel/blob/main/ipykernel/kernelbase.py#L1283
                 start_new_session=True,
             )
-        except Exception as e:
-            log.error("Failed to create posix subprocess: %s", e)
-            return None
-    else:
-        try:
+        else:
             log.debug("Starting matlab proxy subprocess for windows")
             return subprocess.Popen(
                 cmd,
                 env=env,
             )
-        except Exception as e:
-            log.error("Failed to create windows subprocess: %s", e)
-            return None
+    except Exception as e:
+        log.error("Failed to create matlab-proxy subprocess: %s", e)
+        raise exceptions.ProcessStartError(extra_info=str(e)) from e
 
 
 async def shutdown(parent_pid: str, caller_id: str, mpm_auth_token: str):
@@ -305,10 +347,10 @@ async def shutdown(parent_pid: str, caller_id: str, mpm_auth_token: str):
         )
         return
 
+    filename = f"{parent_pid}_{caller_id}"
     try:
         data_dir = helpers.create_and_get_proxy_manager_data_dir()
         storage = FileRepository(data_dir)
-        filename = f"{parent_pid}_{caller_id}"
         full_file_path, server = storage.get(filename)
 
         if not server:

matlab_proxy_manager/storage/server.py

@@ -101,8 +101,11 @@ class ServerProcess:
 
             # Force kill matlab-proxy and its process tree if termination
             # via shutdown_integration endpoint fails
-            matlab_proxy_process = psutil.Process(int(self.pid))
-            self.terminate_process_tree(matlab_proxy_process)
+            try:
+                matlab_proxy_process = psutil.Process(int(self.pid))
+                self.terminate_process_tree(matlab_proxy_process)
+            except Exception as e:
+                log.debug("Exception while terminating child processes: %s", e)
             return None
 
     def terminate_process_tree(self, matlab_proxy_process):

matlab_proxy_manager/utils/constants.py

@@ -1,5 +1,6 @@
-# Copyright 2024 The MathWorks, Inc.
+# Copyright 2024-2025 The MathWorks, Inc.
 
 MWI_BASE_URL_PREFIX = "/matlab/"
+MWI_DEFAULT_MATLAB_PATH = MWI_BASE_URL_PREFIX + "default"
 HEADER_MWI_MPM_CONTEXT = "MWI-MPM-CONTEXT"
 HEADER_MWI_MPM_AUTH_TOKEN = "MWI-MPM-AUTH-TOKEN"

matlab_proxy_manager/utils/environment_variables.py

@@ -1,4 +1,4 @@
-# Copyright 2020-2024 The MathWorks, Inc.
+# Copyright 2020-2025 The MathWorks, Inc.
 """This file lists and exposes the environment variables which are used by proxy manager."""
 
 import os
@@ -41,6 +41,11 @@ def get_env_name_mwi_mpm_parent_pid():
     return "MWI_MPM_PARENT_PID"
 
 
+def get_env_name_base_url_prefix():
+    """Used to specify the base url prefix for setting base url on matlab (e.g. Jupyter base url)"""
+    return "MWI_MPM_BASE_URL_PREFIX"
+
+
 def is_web_logging_enabled():
     """Returns true if the web logging is required to be enabled"""
     return _is_env_set_to_true(get_env_name_enable_web_logging())

matlab_proxy_manager/utils/exceptions.py

@@ -0,0 +1,45 @@
+# Copyright 2025 The MathWorks, Inc.
+
+
+class MATLABProxyError(Exception):
+    """Base class for all MATLAB Proxy Manager exceptions."""
+
+    pass
+
+
+class ProcessStartError(MATLABProxyError):
+    """Exception thrown when MATLAB proxy process fails to start."""
+
+    def __init__(
+        self, message="Failed to create matlab-proxy subprocess.", extra_info=None
+    ):
+        self.message = message
+        self.extra_info = extra_info
+        super().__init__(message)
+
+    def __str__(self):
+        return (
+            f"{self.message} Additional info: {self.extra_info}"
+            if self.extra_info
+            else self.message
+        )
+
+
+class ServerReadinessError(MATLABProxyError):
+    """Exception thrown when MATLAB proxy server fails to become ready"""
+
+    def __init__(
+        self,
+        message="MATLAB Proxy Server unavailable: matlab-proxy-app failed to start or has timed out.",
+        extra_info=None,
+    ):
+        self.message = message
+        self.extra_info = extra_info
+        super().__init__(message)
+
+    def __str__(self):
+        return (
+            f"{self.message} Additional info: {self.extra_info}"
+            if self.extra_info
+            else self.message
+        )

matlab_proxy_manager/utils/helpers.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The MathWorks, Inc.
+# Copyright 2024-2025 The MathWorks, Inc.
 import http
 import os
 import socket
@@ -204,7 +204,7 @@ def poll_for_server_deletion() -> None:
     Logs the status of server deletion attempts.
     """
     timeout_in_seconds: int = 2
-    log.info("Interrupt/termination signal caught, cleaning up resources")
+    log.debug("Interrupt/termination signal caught, cleaning up resources")
     start_time = time.time()
 
     while time.time() - start_time < timeout_in_seconds:

matlab_proxy_manager/utils/logger.py

@@ -1,4 +1,4 @@
-# Copyright 2024 The MathWorks, Inc.
+# Copyright 2024-2025 The MathWorks, Inc.
 # Helper functions to access & control the logging behavior of the app
 
 import logging
@@ -56,6 +56,9 @@ def __set_logging_configuration():
     # 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