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

matlab_proxy/util/mwi/validators.py

@@ -1,30 +1,36 @@
-# Copyright (c) 2020-2022 The MathWorks, Inc.
-"""This file contains validators for various runtime artefacts.
-A validator is defined as a function which verifies the input and 
-returns it unchanged if validation passes. 
+# Copyright 2020-2025 The MathWorks, Inc.
+"""This file contains validators for various runtime artifacts.
+A validator is defined as a function which verifies the input and
+returns it unchanged if validation passes.
 Returning inputs allows validators to be used inline with the input.
 
-Example: 
+Example:
 Original code: if( input ):
 With validator: if (valid(input)):
 
 Exceptions are thrown to signal failure.
 """
+
 import errno
+import math
 import os
 import socket
-import sys
+from pathlib import Path
+from typing import List
 
 import matlab_proxy
-import pkg_resources
+from matlab_proxy import util
+from matlab_proxy.constants import VERSION_INFO_FILE_NAME
+from matlab_proxy.util import system
 
 from . import environment_variables as mwi_env
 from . import logger as mwi_logger
+from .exceptions import FatalError, MatlabInstallError
 
 logger = mwi_logger.get()
 
 
-def validate_mlm_license_file(nlm_conn_str):
+def validate_mlm_license_file(nlm_connections_str):
     """Validates and returns input if it passes validation.
     Throws exception when validation fails.
     The connection string should be in the form of port@hostname
@@ -39,44 +45,65 @@ def validate_mlm_license_file(nlm_conn_str):
     Returns:
         String: Returns the same argument passed to this function if its valid.
     """
+
+    """
+     nlm_connections_str can either be a valid path to a file or a
+     string with comma seperated values, each of the form port@hostname
+    
+    Some valid nlm_connections_str values are:
+    1) port@hostname
+    2) port@hostname,
+    3) port1@hostname1,port2@hostname2
+    4) port1@hostname1,port2@hostname2,
+    5) port1@hostname1,port2@hostname2,port3@hostname3,
+    """
     import re
 
     from .exceptions import NetworkLicensingError
 
-    if nlm_conn_str is None:
+    if not nlm_connections_str:
+        # Handles empty strings and None values
         return None
 
-    # TODO: The JS validation of this setting does not allow file path locations
-    # The JS validation occurs before reaching the set_licensing_info endpoint.
-
     # Regular expression to match port@hostname,
     # where port is any number and hostname is alphanumeric
     # regex = Start of Line, Any number of 0-9 digits , @, any number of nonwhite space characters with "- _ ." allowed
     # "^[0-9]+[@](\w|\_|\-|\.)+$"
-    # Server triad is of the form : port@host1,port@host2,port@host3
-    regex = "(^[0-9]+[@](\w|\_|\-|\.)+$)|(^[0-9]+[@](\w|\_|\-|\.)+),([0-9]+[@](\w|\_|\-|\.)+),([0-9]+[@](\w|\_|\-|\.)+$)"
-    if not re.search(regex, nlm_conn_str):
-        logger.debug("NLM info is not in the form of port@hostname")
-        if not os.path.isfile(nlm_conn_str):
-            logger.debug("NLM info is not a valid path to a license file")
-            error_message = (
-                f"MLM_LICENSE_FILE validation failed for {nlm_conn_str}. "
-                f"If set, the MLM_LICENSE_FILE environment variable must be a string which is either of the form port@hostname"
-                f" OR path to a valid license file."
-            )
-            logger.error(error_message)
-            raise NetworkLicensingError(error_message)
-        else:
+    # Server triad is of the form : port@host1 or port@host1,port@host2,port@host3
+    nlm_connection_str_regex = r"(^[0-9]+[@](\w|\_|\-|\.)+$)"
+    error_message = (
+        f"MLM_LICENSE_FILE validation failed for {nlm_connections_str}. "
+        f"If set, the MLM_LICENSE_FILE environment variable must contain server names (each of the form port@hostname) separated by ':' on unix or ';' on windows(server triads however must be comma seperated)"
+        f" OR path to a valid license file."
+    )
+
+    seperator = system.get_mlm_license_file_seperator()
+    nlm_connection_strs = re.split(f"{seperator}|,", nlm_connections_str)
+
+    logger.debug(
+        "Validating individual parts of the environment variable MLM_LICENSE_FILE"
+    )
+    for nlm_connection_str in nlm_connection_strs:
+        # Individual parts of the MLM_LICENSE_FILE can either be a valid path to a license file or a server name.
+
+        if os.path.isfile(nlm_connection_str):
             logger.info(
-                f"MLM_LICENSE_FILE with value: {nlm_conn_str} is a path to a file. MATLAB will attempt to use it."
+                f"{nlm_connections_str} is a path to a file. MATLAB will attempt to use it."
             )
-    else:
-        logger.info(
-            f"MLM_LICENSE_FILE with value: {nlm_conn_str} is a license server, MATLAB will attempt to connect to it."
-        )
 
-    # Validation passed
-    return nlm_conn_str
+        else:
+            match = re.search(nlm_connection_str_regex, nlm_connection_str)
+
+            if match:
+                logger.debug(f"Successfully validated {nlm_connection_str}")
+            else:
+                logger.error(f"Failed to validate:{nlm_connection_str}")
+                logger.error(
+                    "NLM_info is not of the form port@hostname or a valid path to a file"
+                )
+                raise NetworkLicensingError(error_message)
+
+    return nlm_connections_str
 
 
 def validate_app_port_is_free(port):
@@ -107,10 +134,9 @@ def validate_app_port_is_free(port):
         return port
     except socket.error as e:
         if e.errno == errno.EADDRINUSE:
-            logger.error(
-                f"The port {port} is not available. Please set another value for the environment variable {mwi_env.get_env_name_app_port()}"
-            )
-            sys.exit(1)
+            error_message = f"The port {port} is not available. Please set another value for the environment variable {mwi_env.get_env_name_app_port()}"
+            logger.error(error_message)
+            raise FatalError(error_message)
         else:
             raise e
 
@@ -134,10 +160,9 @@ def validate_base_url(base_url):
 
     else:
         if not base_url.startswith("/"):
-            logger.error(
-                f'The value of environment variable {mwi_env.get_env_name_base_url()} must start with "/" '
-            )
-            sys.exit(1)
+            error_message = f'The value of environment variable {mwi_env.get_env_name_base_url()} must start with "/" '
+            logger.error(error_message)
+            raise FatalError(error_message)
 
         validated_base_url = base_url[:-1] if base_url.endswith("/") else base_url
 
@@ -154,30 +179,31 @@ def validate_env_config(config):
     Returns:
         Dict: Containing data specific to the environment in which MATLAB proxy is being used in.
     """
-    available_configs = __get_configs()
+    from matlab_proxy.default_configuration import get_required_config
+
+    available_configs: dict = __get_configs()
     config = config.lower()
 
     # Check if supplied config is present in the available configs
     if config in available_configs:
-        # Check if all keys are present in the supplied config
-        default_config_keys = available_configs[
-            matlab_proxy.get_default_config_name()
-        ].keys()
         env_config = available_configs[config]
+        required_keys = get_required_config()
 
-        for key in default_config_keys:
-            if not key in env_config:
-                logger.error(f"{key} missing in the provided {config} configuration")
-                sys.exit(1)
+        # Check if all required keys are present in the supplied config
+        valid = all(key in env_config for key in required_keys)
+        if not valid:
+            error_message = (
+                f"Required key/s missing in the provided {config} configuration"
+            )
+            logger.error(error_message)
+            raise FatalError(error_message)
 
-        logger.debug(f"Successfully validated provided {config} configuration")
+        logger.debug("Successfully validated provided %s configuration", config)
         return env_config
 
-    else:
-        logger.error(
-            f"{config} is not a valid config. Available configs are : {list(available_configs.keys())}"
-        )
-        sys.exit(1)
+    error_message = f"{config} is not a valid config. Available configs are : {list(available_configs.keys())}"
+    logger.error(error_message)
+    raise FatalError(error_message)
 
 
 def __get_configs():
@@ -188,56 +214,173 @@ def __get_configs():
         Dict: Contains all the values present in 'matlab_web_desktop_configs' entry_point from all the packages
         installed in the current environment.
     """
+    import importlib.metadata as metadata
+
+    matlab_proxy_eps = metadata.entry_points(group=matlab_proxy.get_entrypoint_name())
     configs = {}
-    for entry_point in pkg_resources.iter_entry_points(
-        matlab_proxy.get_entrypoint_name()
-    ):
+    for entry_point in matlab_proxy_eps:
         configs[entry_point.name.lower()] = entry_point.load()
 
     return configs
 
 
-def validate_ssl_cert_file(a_ssl_cert_file):
+def validate_ssl_file(ssl_file, env_name):
     """Ensures that its a valid readable file"""
 
     # Empty strings are valid inputs
-    if a_ssl_cert_file:
-        # String is not empty, check to see if the file exists
-        if not os.path.isfile(a_ssl_cert_file):
-            logger.error(f"MWI_SSL_CERT_FILE is not a valid file: {a_ssl_cert_file}")
-            sys.exit(1)
-
-    # string is either empty, or is a valid file on disk
-    return a_ssl_cert_file
+    if not ssl_file:
+        return None
 
+    # String is not empty, check to see if the file exists
+    if not os.path.isfile(ssl_file):
+        error_message = f"{env_name} is not a valid file: {ssl_file}"
+        logger.error(error_message)
+        raise FatalError(error_message)
 
-def validate_ssl_key_and_cert_file(a_ssl_key_file, a_ssl_cert_file):
-    """Ensures that its a valid readable file"""
+    # string is a valid file on disk
+    return ssl_file
 
-    if a_ssl_cert_file is None and a_ssl_key_file is None:
-        # Both values are None, this is acceptable.
-        return a_ssl_key_file, a_ssl_cert_file
 
-    # Implies atleast one value is not None.
+def validate_ssl_key_and_cert_file(ssl_key_file, ssl_cert_file):
+    """Validates that provided SSL files are valid readable files"""
+    env_name_ssl_cert_file = mwi_env.get_env_name_ssl_cert_file()
+    env_name_ssl_key_file = mwi_env.get_env_name_ssl_key_file()
 
-    # Cert file is either empty or valid file.
-    cert_file = validate_ssl_cert_file(a_ssl_cert_file=a_ssl_cert_file)
+    if not ssl_cert_file and not ssl_key_file:
+        # Both values are falsy, this is acceptable and signify that HTTPS communication is disabled.
+        return None, None
 
-    if cert_file is None and a_ssl_key_file is not None:
-        logger.error(f"MWI_SSL_CERT_FILE must be provided to use the MWI_SSL_KEY_FILE")
-        sys.exit(1)
+    # Implies at least one value is not falsy.
 
-    if a_ssl_key_file is None and cert_file is not None:
+    # Validating cert file- Cert file is either empty or valid file.
+    cert_file = validate_ssl_file(
+        ssl_file=ssl_cert_file, env_name=env_name_ssl_cert_file
+    )
+    if not cert_file:
+        error_message = f"{env_name_ssl_cert_file} must be provided to use the {env_name_ssl_key_file}"
+        logger.error(error_message)
+        raise FatalError(error_message)
+
+    # Validating key file
+    key_file = validate_ssl_file(ssl_file=ssl_key_file, env_name=env_name_ssl_key_file)
+    if not ssl_key_file:
         logger.info(
-            f"MWI_SSL_KEY_FILE is not provided, ensure that your MWI_SSL_CERT_FILE : '{cert_file}' contains a private key"
+            f"{env_name_ssl_key_file} is not provided, ensure that your {env_name_ssl_cert_file} : '{cert_file}' contains a private key"
         )
 
-    if a_ssl_key_file:
-        if not os.path.isfile(a_ssl_key_file):
-            logger.error(f"MWI_SSL_KEY_FILE is not a valid file: {a_ssl_key_file}")
-            sys.exit(1)
-
     logger.info(
-        f"SSL Keys provided were: MWI_SSL_CERT_FILE: {a_ssl_cert_file} & MWI_SSL_KEY_FILE: {a_ssl_key_file}"
+        f"SSL Keys provided were: {env_name_ssl_cert_file}: {cert_file} & {env_name_ssl_key_file}: {key_file}"
     )
-    return a_ssl_key_file, a_ssl_cert_file
+    return key_file, cert_file
+
+
+def validate_use_existing_licensing(use_existing_license):
+    """Returns true if use_existing_license is true
+
+    Args:
+        use_existing_license (str): value from the environment variable MWI_USE_EXISTING_LICENSE
+
+    Returns:
+        bool: if use_existing_license is set to true
+    """
+    return True if use_existing_license.casefold() == "true" else False
+
+
+def __validate_if_paths_exist(paths: List[Path]):
+    """Validates if  paths of directories or files exists on the file system.
+
+    Args:
+        paths ([pathlib.Path]): List of pathlib.Path's to directories or files
+
+    Raises:
+        OSError: When an invalid path is supplied
+
+    Returns:
+        [pathlib.Path] | None: [pathlib.Path] if valid paths are supplied else None
+    """
+    for path in paths:
+        if not util.is_valid_path(path):
+            raise OSError(f"Supplied invalid path:{path}")
+
+    return paths
+
+
+def validate_matlab_root_path(matlab_root: Path, is_custom_matlab_root: bool):
+    """Validate if path supplied is MATLAB_ROOT by checking for the existence of VersionInfo.xml file
+    at matlab_root.
+
+    Args:
+        path (pathlib.Path): path to MATLAB root
+
+    Returns:
+        pathlib.Path | None: pathlib.Path if a valid path to MATLAB root is supplied else None
+
+    Raises:
+        MatlabInstallError
+    """
+
+    # When Custom MATLAB root is provided, validate the existence of the
+    # VersionInfo.xml file at the specified path else, its optional (for matlab wrapper usecase)
+    custom_matlab_root_warn_str = f"Edit the environment variable {mwi_env.get_env_name_custom_matlab_root()} to the correct path, and restart matlab-proxy. "
+
+    try:
+        __validate_if_paths_exist([matlab_root])
+        logger.debug(
+            f"MATLAB root path: {matlab_root} exists, continuing to verify its validity..."
+        )
+
+    except OSError as exc:
+        logger.error(". ".join(exc.args))
+        raise MatlabInstallError(
+            custom_matlab_root_warn_str if is_custom_matlab_root else ""
+        )
+
+    version_info_file_path = matlab_root / VERSION_INFO_FILE_NAME
+
+    if not version_info_file_path.is_file():
+        warn_str = f"Unable to locate {VERSION_INFO_FILE_NAME} at {matlab_root}"
+        # If VersionInfo.xml file is missing when a custom MATLAB root is provided, then
+        # raise an error with a detailed message
+        if is_custom_matlab_root:
+            log_error_string = custom_matlab_root_warn_str + warn_str
+            raise MatlabInstallError(log_error_string)
+
+        else:
+            # No VersionInfo.xml file is present and its not a custom MATLAB root, implies a matlab wrapper is
+            # being used, so warn the user and return None as MATLAB root could not be determined
+            logger.warning(warn_str)
+            return None
+
+    return matlab_root
+
+
+def validate_idle_timeout(timeout):
+    """Validate if IDLE timeout for matlab-proxy
+
+    Args:
+        timeout (None | int): IDLE timeout for shutdown of matlab-proxy.
+
+    Raises:
+        ValueError: If a non-numerical value is supplied other than None.
+
+    Returns:
+        None | int : The timeout value.
+    """
+    if not timeout:
+        return timeout
+
+    try:
+        # Convert timeout to seconds
+        timeout = math.ceil(float(timeout) * 60)
+
+        if timeout <= 0:
+            raise ValueError
+
+        logger.info(f"MATLAB IDLE timeout set to {timeout} seconds")
+        return timeout
+
+    except ValueError:
+        logger.warning(
+            f"Invalid value supplied for {mwi_env.get_env_name_shutdown_on_idle_timeout()}: {timeout}. Continuing without any IDLE timeout."
+        )
+        return None

matlab_proxy/util/system.py

@@ -63,3 +63,12 @@ def get_supported_termination_signals():
         if is_posix()
         else [signal.SIGINT, signal.SIGTERM]
     )
+
+
+def get_mlm_license_file_seperator():
+    """Returns OS specific seperator for MLM_LICENSE_FILE environment variable
+
+    Returns:
+        str: OS specific seperator for MLM_LICENSE_FILE
+    """
+    return ":" if is_posix() else ";"

matlab_proxy/util/windows.py

@@ -1,9 +1,12 @@
-# Copyright 2022 The MathWorks, Inc.
+# Copyright 2022-2024 The MathWorks, Inc.
 import asyncio
 
 from matlab_proxy import util
 from matlab_proxy.util import mwi
 from matlab_proxy.util.mwi import environment_variables as mwi_env
+from matlab_proxy.util.mwi.exceptions import (
+    UIVisibleFatalError,
+)
 
 """ This file contains methods specific to non-posix / windows OS.
 """
@@ -43,23 +46,28 @@ async def start_matlab(matlab_cmd, matlab_env):
     Returns:
         psutil.Process(): The MATLAB process object.
     """
+    import psutil
 
+    # The stdout is used to suppress the MATLAB outputs from being shown in the terminal.
+    # We set it to DEVNULL instead of PIPE because PIPE has a limited buffer size and can
+    # block the process if the output exceeds the buffer limit.
     intermediate_proc = await asyncio.create_subprocess_exec(
         *matlab_cmd,
         env=matlab_env,
+        stdout=asyncio.subprocess.DEVNULL,
         stderr=asyncio.subprocess.STDOUT,
     )
 
     # In testing mode, the devel.py file is run, which is the fake MATLAB server.
     # So, there is no need to check for an intermediate process when testing and can return
     # the same process as a psutil.Process() object.
-    if mwi_env.is_testing_mode_enabled():
-        import psutil
-
+    if mwi_env.is_testing_mode_enabled() or mwi_env.is_development_mode_enabled():
         proc = psutil.Process(intermediate_proc.pid)
 
         return proc
 
+    matlab = None
+
     try:
         children = util.get_child_processes(intermediate_proc)
 
@@ -74,8 +82,26 @@ async def start_matlab(matlab_cmd, matlab_env):
             "MATLAB.exe" == matlab.name()
         ), "Expecting the child process name to be MATLAB.exe"
 
-    except AssertionError as err:
+    except (AssertionError, UIVisibleFatalError) as err:
         raise err
 
+    except psutil.NoSuchProcess:
+        # We reach here when the intermediate process launched by matlab-proxy died
+        # before we can query for its child processes. Hence, to find the actual MATLAB
+        # process, we check all the processes name and parent process id. Ideally, this
+        # approach should work in all cases unless MATLAB itself has exited / crashed.
+        logger.debug(
+            "Intermediate process not found. Querying all process to find MATLAB"
+        )
+        for process in psutil.process_iter():
+            if (
+                process.name() == "MATLAB.exe"
+                and process.ppid() == intermediate_proc.pid
+            ):
+                matlab = process
+                break
+
+    assert matlab != None, "MATLAB Process ID not found"
+
     # Return the actual MATLAB processes
-    return children[0]
+    return matlab