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

matlab_proxy/util/mwi/download.py

@@ -0,0 +1,136 @@
+# Copyright 2024-2025 The MathWorks, Inc.
+
+# This file contains functions required to enable downloads from the file browser
+from matlab_proxy.util.mwi import logger as mwi_logger
+from matlab_proxy.util import mwi, system
+
+logger = mwi_logger.get()
+
+
+def _is_null_base_url(base_url):
+    return base_url == "/" or base_url == ""
+
+
+def is_download_request(req):
+    """
+    Determine if the incoming request is for a download action.
+
+    This function checks if the request's relative URL path starts with
+    '/download/' or with '{base_url}/download/', depending on the base URL
+    specified in the application settings.
+
+    Parameters:
+        req (HTTPRequest): HTTPRequest Object
+
+    Returns:
+    - bool: True if the request is for a download, False otherwise.
+    ```
+    """
+
+    base_url = req.app["settings"]["base_url"]
+    if _is_null_base_url(base_url):
+        return req.rel_url.path.startswith("/download")
+    else:
+        return req.rel_url.path.startswith(f"{base_url}/download")
+
+
+async def get_download_url(req):
+    """
+    Asynchronously generates a download URL for a file.
+
+    This function takes a request object, extracts the full path to the file, and
+    uses the MATLAB Web Interface (MWI) to generate a download URL for that file.
+    It logs the full path and the response from the MWI. If successful, it returns
+    the download URL; otherwise, it returns None.
+
+    Parameters:
+        The request object containing necessary information to process the download.
+    Returns:
+        The download URL string if successful, None otherwise.
+    Raises:
+        Logs an error message and returns None if an error occurs.
+    """
+    full_path_to_file = _get_download_payload_path(req)
+    logger.debug(f"full_path_to_file: {full_path_to_file}")
+
+    args = [full_path_to_file, 1.0]
+    data = mwi.embedded_connector.helpers.get_data_to_feval_mcode(
+        "matlab.ui.internal.URLUtils.getURLToUserFile", *args, nargout=1
+    )
+
+    try:
+        state = req.app["state"]
+        headers = state._get_token_auth_headers()
+        url = mwi.embedded_connector.helpers.get_mvm_endpoint(
+            state.settings["mwi_server_url"]
+        )
+        resp_json = await mwi.embedded_connector.send_request(
+            url=url,
+            method="POST",
+            data=data,
+            headers=headers,
+        )
+
+        logger.debug(f"EC Response URL: {resp_json}")
+
+        resp = resp_json["messages"]["FEvalResponse"][0]
+
+        if not resp["isError"]:
+            # No error detected, proceed to fetch the results
+            download_url = resp["results"][0]
+            logger.debug(f"download_url: {download_url}")
+            base_url = req.app["settings"]["base_url"]
+            return (
+                download_url
+                if _is_null_base_url(base_url)
+                else f"{base_url}{download_url}"
+            )
+
+    except KeyError as key_err:
+        logger.error(f"Invalid Key Usage Detected! Check key: {key_err}")
+        pass
+
+    except Exception as err:
+        logger.error(
+            f"Failed to create download url from the Embedded Connector due to err: {err}"
+        )
+        pass
+
+    # In case of any failures.
+    return None
+
+
+def _get_download_payload_path(req):
+    """
+    Constructs the file system path to the payload for a download request.
+
+    This function analyzes the incoming request to determine the intended file path
+    for download. It takes into account the base URL from the application settings,
+    the nature of the request (whether it's a download request), and the operating
+    system to format the path correctly. The function supports different path
+    formatting for Windows and Unix-like systems due to their differences in file
+    system path syntax.
+
+    Note:
+        This function is intended to be used internally and starts with an underscore
+        to indicate it is a private member of the module.
+
+    Args:
+        req: An object representing the incoming request, which includes the relative
+             URL from which the file path can be deduced.
+
+    Returns:
+        A string representing the file system path to the requested download payload,
+        or None if the request is not a download request.
+    """
+    base_url = req.app["settings"]["base_url"]
+    if is_download_request(req):
+        from pathlib import Path
+
+        compare_str = (
+            "/download" if _is_null_base_url(base_url) else f"{base_url}/download"
+        )
+
+        return str(req.rel_url.path).replace(compare_str, "", 1)
+
+    return None

matlab_proxy/util/mwi/embedded_connector/__init__.py

@@ -1,4 +1,4 @@
 # Copyright (c) 2020-2022 The MathWorks, Inc.
 
 from . import helpers
-from .request import get_state, send_request
+from .request import get_busy_state, send_request

matlab_proxy/util/mwi/embedded_connector/helpers.py

@@ -1,8 +1,7 @@
-# Copyright (c) 2020-2022 The MathWorks, Inc.
-
-""" This file contains helper methods which return the details required for sending
-a HTTP request to the Embedded Connector. """
+# Copyright 2020-2024 The MathWorks, Inc.
 
+"""This file contains helper methods which return the details required for sending
+a HTTP request to the Embedded Connector."""
 
 from matlab_proxy.util import mwi
 from matlab_proxy.util.mwi import environment_variables as mwi_env
@@ -46,6 +45,15 @@ def get_data_for_ping_request():
     return {"messages": {"Ping": [{}]}}
 
 
+def get_data_for_matlab_busy_status_request():
+    """Returns data required to send in the payload for a MATLAB busy/idle status request to the embedded connector
+
+    Returns:
+        dict: Payload data
+    """
+    return {"messages": {"GetMatlabStatus": [{}]}}
+
+
 def get_data_to_eval_mcode(m_code):
     """Returns the data required to send in the payload for evaluating mcode using eval function to the embedded connector.
 

matlab_proxy/util/mwi/embedded_connector/request.py

@@ -1,6 +1,6 @@
-# Copyright (c) 2020-2022 The MathWorks, Inc.
+# Copyright 2020-2024 The MathWorks, Inc.
 
-""" 
+"""
 This file contains the methods to communicate with the embedded connector.
 """
 
@@ -8,7 +8,15 @@ import json
 
 from matlab_proxy.util.mwi.exceptions import EmbeddedConnectorError
 
-from .helpers import get_data_for_ping_request, get_ping_endpoint
+from matlab_proxy.util import mwi
+
+logger = mwi.logger.get()
+
+from .helpers import (
+    get_data_for_ping_request,
+    get_data_for_matlab_busy_status_request,
+    get_ping_endpoint,
+)
 
 
 async def send_request(url: str, data: dict, method: str, headers: dict = None) -> dict:
@@ -38,12 +46,16 @@ async def send_request(url: str, data: dict, method: str, headers: dict = None)
         data = json.dumps(data)
 
     try:
-        async with aiohttp.ClientSession() as session:
+        async with aiohttp.ClientSession(trust_env=True) as session:
+            logger.debug(
+                f"sending request: method={method}, url={url}, data={data}, headers={headers}, "
+            )
+
             async with session.request(
-                method=method, url=url, data=data, headers=None, ssl=False
+                method=method, url=url, data=data, headers=headers, ssl=False
             ) as resp:
-                if resp.reason != "OK":
-
+                logger.debug(f"response from endpoint{url} and resp={resp}")
+                if not resp.ok:
                     # Converting to dict and formatting for printing
                     data = json.loads(data)
 
@@ -56,22 +68,76 @@ async def send_request(url: str, data: dict, method: str, headers: dict = None)
         raise err
 
 
-async def get_state(mwi_server_url):
+async def get_state(mwi_server_url, headers=None):
     """Returns the state of MATLAB's Embedded Connector.
 
     Args:
         port (int): The port on which the embedded connector is running at
-
+        headers: Headers to include with the request
     Returns:
         str: Either "up" or "down"
     """
     data = get_data_for_ping_request()
     url = get_ping_endpoint(mwi_server_url)
+
     try:
-        resp = await send_request(url=url, data=data, method="POST")
+        resp = await send_request(
+            url=url,
+            data=data,
+            method="POST",
+            headers=headers,
+        )
+
+        # Any changes in response from embedded connector would be caught by KeyError
         if not resp["messages"]["PingResponse"][0]["messageFaults"]:
             return "up"
-    except Exception:
-        pass
+
+    except KeyError as key_err:
+        logger.error(f"Invalid Key Usage Detected! Check key: {key_err}")
+
+    except Exception as err:
+        logger.debug(
+            f"{err}: Embbeded connector is currently not responding to ping requests."
+        )
 
     return "down"
+
+
+async def get_busy_state(mwi_server_url, headers=None):
+    """Returns the state of MATLAB's Embedded Connector.
+
+    Args:
+        port (int): The port on which the embedded connector is running at
+        headers: Headers to include with the request
+    Returns:
+        str: Either "idle" or "busy" when a valid response is received. Else None is returned.
+    """
+    data = get_data_for_matlab_busy_status_request()
+    url = get_ping_endpoint(mwi_server_url)
+
+    busy_status = None
+
+    try:
+        resp = await send_request(
+            url=url,
+            data=data,
+            method="POST",
+            headers=headers,
+        )
+
+        busy_status = resp["messages"]["GetMatlabStatusResponse"][0]["status"].lower()
+
+        assert busy_status in [
+            "idle",
+            "busy",
+        ], f"Was expecting MATLAB busy status to be either 'idle' or 'busy', but received {busy_status} instead."
+
+    except KeyError as key_err:
+        logger.error(f"Invalid Key Usage Detected! Check key: {key_err}")
+
+    except Exception as err:
+        logger.debug(
+            f"{err}: Embedded connector is currently not responding to ping requests."
+        )
+
+    return busy_status

matlab_proxy/util/mwi/environment_variables.py

@@ -1,9 +1,33 @@
-# Copyright (c) 2020-2022 The MathWorks, Inc.
+# Copyright 2020-2025 The MathWorks, Inc.
 """This file lists and exposes the environment variables which are used by the integration."""
 
 import os
 
 
+def _is_env_set_to_true(env_name: str) -> bool:
+    """Helper function that returns True if the environment variable specified is set to True.
+
+    Args:
+        env_name (str): Name of the environment variable to check the state for.
+
+    Returns:
+        bool: True if the value of the environment variable is a case insensitive match to the string "True"
+    """
+    return os.environ.get(env_name, "false").lower() == "true"
+
+
+def _is_env_set_to_false(env_name: str) -> bool:
+    """Helper function that returns True if the environment variable specified is set to False.
+
+    Args:
+        env_name (str): Name of the environment variable to check the state for.
+
+    Returns:
+        bool: True if the value of the environment variable is a case insensitive match to the string "False"
+    """
+    return os.environ.get(env_name, "").lower() == "false"
+
+
 def get_env_name_network_license_manager():
     """Specifies the path to valid license file or address of a network license server"""
     return "MLM_LICENSE_FILE"
@@ -20,19 +44,10 @@ def get_env_name_logging_level():
 
 
 def get_env_name_enable_web_logging():
-    """wef > v0.2.10 Enable the logging of asyncio web traffic by setting to true"""
+    """Enable the logging of asyncio web traffic by setting to true"""
     return "MWI_ENABLE_WEB_LOGGING"
 
 
-def get_old_env_name_enable_web_logging():
-    """
-    Enable the logging of asyncio web traffic by setting to true
-    This name is deprecated and was last published in version v0.2.10 of matlab-proxy.
-    """
-
-    return "MWI_WEB_LOGGING_ENABLED"
-
-
 def get_env_name_log_file():
     """Specifies a file into which logging content is directed"""
     return "MWI_LOG_FILE"
@@ -89,32 +104,22 @@ def get_env_name_matlab_tempdir():
 
 def is_development_mode_enabled():
     """Returns true if the app is in development mode."""
-    return os.environ.get(get_env_name_development(), "false").lower() == "true"
+    return _is_env_set_to_true(get_env_name_development())
 
 
 def is_testing_mode_enabled():
     """Returns true if the app is in testing mode."""
-    return (
-        is_development_mode_enabled()
-        and os.environ.get(get_env_name_testing(), "false").lower() == "true"
-    )
+    return is_development_mode_enabled() and _is_env_set_to_true(get_env_name_testing())
 
 
 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())
 
-    if os.environ.get(get_old_env_name_enable_web_logging(), None) is not None:
-        from matlab_proxy.util import mwi
 
-        logger = mwi.logger.get()
-        logger.warning(
-            f"Usage of {get_old_env_name_enable_web_logging()} is being deprecated from v0.2.10 and will be removed in a future release.\n Use {get_env_name_enable_web_logging()} instead. "
-        )
-        return (
-            os.environ.get(get_old_env_name_enable_web_logging(), "false").lower()
-            == "true"
-        )
-    return os.environ.get(get_env_name_enable_web_logging(), "false").lower() == "true"
+def get_env_name_enable_ssl():
+    """Returns the environment variable used for enabling/disabling SSL/TLS communication."""
+    return "MWI_ENABLE_SSL"
 
 
 def get_env_name_ssl_cert_file():
@@ -135,3 +140,91 @@ def get_env_name_enable_mwi_auth_token():
 def get_env_name_mwi_auth_token():
     """User specified token for use with Token-Based Authentication"""
     return "MWI_AUTH_TOKEN"
+
+
+def get_env_name_matlab_log_dir():
+    """Returns the key used for MATLAB log dir env variable"""
+    return "MATLAB_LOG_DIR"
+
+
+def get_env_name_mwi_use_existing_license():
+    """Returns the environment variable name used to instruct matlab-proxy to use an existing license. Usually used by already activated MATLAB installations."""
+    return "MWI_USE_EXISTING_LICENSE"
+
+
+def get_env_name_custom_matlab_root():
+    """User specified path to MATLAB root"""
+    return "MWI_CUSTOM_MATLAB_ROOT"
+
+
+def get_env_name_process_startup_timeout():
+    """User specified timeout in seconds for processes launched by matlab-proxy"""
+    return "MWI_PROCESS_START_TIMEOUT"
+
+
+def get_env_name_custom_matlab_code():
+    """User specified MATLAB code that will be executed by matlab-proxy upon its start"""
+    return "MWI_MATLAB_STARTUP_SCRIPT"
+
+
+def get_env_name_shutdown_on_idle_timeout():
+    """User specified timeout in minutes for shutdown on idle of matlab-proxy"""
+    return "MWI_SHUTDOWN_ON_IDLE_TIMEOUT"
+
+
+def get_env_name_session_name():
+    """User specified session name for the MATLAB Proxy instance, used to set the browser title."""
+    return "MWI_SESSION_NAME"
+
+
+class Experimental:
+    """This class houses functions which are undocumented APIs and Environment variables.
+    Note: Never add any state to this class. Its only intended for use as an abstraction layer
+    for functions which are not ready for prime time.
+    """
+
+    @staticmethod
+    def get_env_name_enable_simulink():
+        """Returns the environment variable name used to enable simulink support"""
+        ##NOTE: Simulink Online is unavailable for general use as of R2023b.
+        return "MWI_ENABLE_SIMULINK"
+
+    @staticmethod
+    def is_simulink_enabled():
+        """Returns true if the simulink online is enabled."""
+        return _is_env_set_to_true(Experimental.get_env_name_enable_simulink())
+
+    @staticmethod
+    def get_env_name_profile_matlab_startup():
+        """Returns the environment variable name used to enable MPA support"""
+        return "MWI_PROFILE_MATLAB_STARTUP"
+
+    @staticmethod
+    def is_matlab_startup_profiling_enabled():
+        """Returns true if the startup profiling is enabled."""
+        return _is_env_set_to_true(Experimental.get_env_name_profile_matlab_startup())
+
+    @staticmethod
+    def get_env_name_use_cookie_cache():
+        """Returns the environment variable name used to enable cookie jar support for matlab-proxy"""
+        return "MWI_USE_COOKIE_CACHE"
+
+    @staticmethod
+    def should_use_cookie_cache():
+        """Returns true if the cookie jar support is enabled."""
+        return _is_env_set_to_true(Experimental.get_env_name_use_cookie_cache())
+
+    @staticmethod
+    def get_env_name_use_rich_logging():
+        """Set to True to enable rich logging to console."""
+        return "MWI_USE_RICH_LOGGING"
+
+    @staticmethod
+    def use_rich_logger():
+        """Returns true if the cookie jar support is enabled."""
+        return _is_env_set_to_true(Experimental.get_env_name_use_rich_logging())
+
+    @staticmethod
+    def get_licmode_override():
+        """Returns the licmode oveerride if set"""
+        return os.environ.get("MWI_LICMODE_OVERRIDE", None)

matlab_proxy/util/mwi/exceptions.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2022 The MathWorks, Inc.
+# Copyright 2020-2025 The MathWorks, Inc.
 
 
 class AppError(Exception):
@@ -17,9 +17,19 @@ class AppError(Exception):
         self.stacktrace = stacktrace
 
 
-class InternalError(AppError):
-    """A Class which inherits the AppError class.
-    This class represents any Internal Error within the App
+class FatalError(AppError):
+    """An error which indicates that matlab-proxy web server cannot be brought up.
+    Args:
+        AppError (Class): Parent Class containing attributes to store
+        messages, logs and stacktrace.
+    """
+
+    pass
+
+
+class UIVisibleFatalError(AppError):
+    """A Class with inherits from the AppError class.
+    This class is used to represent Fatal Errors which need to be propagated to the front end.
 
     Args:
         AppError (Class): Parent Class containing attributes to store
@@ -29,7 +39,7 @@ class InternalError(AppError):
     pass
 
 
-class MatlabInstallError(AppError):
+class MatlabInstallError(UIVisibleFatalError):
     """A Class which inherits the AppError class.
 
     This class represents errors with MATLAB Installation.
@@ -129,6 +139,19 @@ class XvfbError(AppError):
     pass
 
 
+class WindowManagerError(AppError):
+    """A Class which inherits the AppError class.
+
+    This class represents any errors raised when instantiating a Window Manager within the Xvfb DISPLAY.
+
+    Args:
+        AppError (Class): Parent Class containing attributes to store
+        messages, logs and stacktrace.
+    """
+
+    pass
+
+
 class EmbeddedConnectorError(MatlabError):
     """A Class which inherits the MatlabError class.
 
@@ -142,6 +165,34 @@ class EmbeddedConnectorError(MatlabError):
     pass
 
 
+class InvalidTokenError(AppError):
+    """A Class which inherits the AppError class.
+
+    This class represents token authentication errors.
+
+    Args:
+        AppError (Class): Parent Class containing attributes to store
+        messages, logs and stacktrace.
+    """
+
+    pass
+
+
+class LockAcquisitionError(Exception):
+    """Exception raised when a lock is not properly acquired before modifying a variable.
+
+    This error is thrown in scenarios where:
+    1) A lock must be acquired before modifying a shared resource, but it wasn't.
+    2) The lock for a shared resource was acquired by one function, but another function attempts to modify the resource without holding the lock.
+
+
+    Args:
+        Exception : Python's inbuilt Exception Class.
+    """
+
+    pass
+
+
 def log_error(logger, err: Exception):
     """Logs any error to stdout.
 
@@ -150,7 +201,10 @@ def log_error(logger, err: Exception):
         err (Class): An instance of one of the  Error classes as defined above.
         Example: OnlineLicensingError, EntitlementError
     """
-    logs_str = ("\n" + "\n".join(err.logs)) if err.logs is not None else ""
-    logger.error(
-        err.message if err.message else "An Exception was raised:\n" + logs_str
-    )
+    if isinstance(err, AppError):
+        logs_str = ("\n" + "\n".join(err.logs)) if err.logs is not None else ""
+        logger.error(
+            err.message if err.message else "An Exception was raised:\n" + logs_str
+        )
+    else:
+        logger.error(err)