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

matlab_proxy/util/__init__.py

@@ -1,18 +1,31 @@
-# Copyright (c) 2020-2022 The MathWorks, Inc.
+# Copyright 2020-2025 The MathWorks, Inc.
 import argparse
+import inspect
 import os
 import socket
-import sys
+import time
+
+from pathlib import Path
 
 import matlab_proxy
 from matlab_proxy.util import mwi, system
 from matlab_proxy.util.event_loop import *
 from matlab_proxy.util.mwi import environment_variables as mwi_env
+from matlab_proxy.util.mwi.exceptions import (
+    UIVisibleFatalError,
+)
+
+from matlab_proxy.util.mwi.exceptions import (
+    LockAcquisitionError,
+)
 
 logger = mwi.logger.get()
 
+# Global value to detect whether interrupt signal handler has been triggered or not.
+interrupt_signal_caught = False
+
 
-def parse_cli_args():
+def parse_main_cli_args():
     """Parses CLI arguments passed to the main() function.
 
     Returns:
@@ -26,9 +39,40 @@ def parse_cli_args():
         help="A json file which stores the config specific to the environment.",
         default=matlab_proxy.get_default_config_name(),
     )
+
+    parser.add_argument(
+        "-v",
+        "--version",
+        help="prints the version of matlab-proxy.",
+        action="store_true",
+    )
+
     args = parser.parse_args()
 
     parsed_args["config"] = args.config
+    parsed_args["version"] = args.version
+
+    return parsed_args
+
+
+def parse_list_cli_args():
+    """Parses CLI arguments passed to the matlab-proxy-app-list-servers entrypoint.
+
+    Returns:
+        dict: Containing the parsed arguments
+    """
+    # Parse the --config flag provided to the console script executable.
+    parsed_args = {}
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        help="Return the server list without any additional text.",
+        action="store_true",
+    )
+    args = parser.parse_args()
+
+    parsed_args["quiet"] = args.quiet
 
     return parsed_args
 
@@ -75,7 +119,7 @@ def prepare_site(app, runner):
                 )
                 break
             except:
-                logger.info(f"Failed to launch the site on port {p}")
+                logger.error(f"Failed to launch the site on port {p}")
 
     return site
 
@@ -97,8 +141,18 @@ def add_signal_handlers(loop):
         Raises:
             SystemExit: Raises SystemExit which will stop execution of loop.run_forever() in app.main()
         """
-        logger.debug("Interrupt Signal handler called with args:\n", *args)
-        raise SystemExit
+        logger.debug("Interrupt Signal handler called")
+
+        # Only raise SystemExit when the handler is invoked for the first time.
+        # Ignore subsequent handler invocations of interrupt signals. This is
+        # required so that asyncio event loop gracefully cancels pending tasks
+        # and exits.
+        global interrupt_signal_caught
+        if interrupt_signal_caught is False:
+            interrupt_signal_caught = True
+            raise SystemExit
+
+        logger.debug("Interrupt is already being serviced.")
 
     for interrupt_signal in system.get_supported_termination_signals():
         logger.debug(f"Registering handler for signal: {interrupt_signal} ")
@@ -115,48 +169,7 @@ def add_signal_handlers(loop):
     return loop
 
 
-def prettify(boundary_filler=" ", text_arr=[]):
-    """Prettify array of strings with borders for stdout
-
-    Args:
-        boundary_filler (str, optional): Upper and lower border filler for text. Defaults to " ".
-        text_arr (list, optional):The text array to prettify. Each element will be added to a newline. Defaults to [].
-
-    Returns:
-        [str]: Prettified String
-    """
-
-    import sys
-
-    if not sys.stdout.isatty():
-        return (
-            "\n============================\n"
-            + "\n".join(text_arr)
-            + "\n============================\n"
-        )
-
-    size = os.get_terminal_size()
-    cols, _ = size.columns, size.lines
-
-    if any(len(text) > cols for text in text_arr):
-        result = ""
-        for text in text_arr:
-            result += text + "\n"
-        return result
-
-    upper = "\n" + "".ljust(cols, boundary_filler) + "\n" if len(text_arr) > 0 else ""
-    lower = "".ljust(cols, boundary_filler) if len(text_arr) > 0 else ""
-
-    content = ""
-    for text in text_arr:
-        content += text.center(cols) + "\n"
-
-    result = upper + content + lower
-
-    return result
-
-
-def get_child_processes(parent_process):
+def get_child_processes(parent_process, max_attempts=10, sleep_interval=1):
     """Get list of child processes from a parent process.
 
     Args:
@@ -174,7 +187,8 @@ def get_child_processes(parent_process):
     # to get hold child processes
     parent_process_psutil = psutil.Process(parent_process.pid)
 
-    while True:
+    child_processes = None
+    for _ in range(max_attempts):
         try:
             # Before checking for any child processes, ensure that the parent process is running
             assert (
@@ -185,13 +199,24 @@ def get_child_processes(parent_process):
 
             if not child_processes:
                 logger.debug("Waiting for the child processes to be created...")
+                time.sleep(sleep_interval)
                 continue
 
+            else:
+                logger.debug(f"Found the child process: {child_processes[0]}")
+                break
+
         except AssertionError as err:
             raise err
 
-        if child_processes:
-            break
+    if not child_processes:
+        logger.debug(
+            f"MATLAB process was not found while searching for the child processes."
+        )
+
+        raise UIVisibleFatalError(
+            "Unable to create MATLAB process. Click Start MATLAB to try again."
+        )
 
     return child_processes
 
@@ -214,17 +239,120 @@ def get_access_url(app):
     access_protocol = "https" if ssl_context else "http"
 
     # When host interface is set to 0.0.0.0, in a windows system, the server will not be accessible.
-    # Setting the value to fqdn, will allow it be remotely and locally accessible.
+    # Setting the value to 127.0.0.1, will allow it be remotely and locally accessible.
 
     # NOTE: When windows container support is introduced this will need to be tweaked accordingly.
     if host_interface == "0.0.0.0" and system.is_windows():
-        import socket
-
-        hostname = socket.gethostname()
-        fqdn = socket.getfqdn(hostname)
+        host_interface = "127.0.0.1"
 
-        url = f"{access_protocol}://{fqdn}:{port}{base_url}"
-    else:
-        url = f"{access_protocol}://{host_interface}:{port}{base_url}"
+    url = f"{access_protocol}://{host_interface}:{port}{base_url}"
 
     return url
+
+
+def is_valid_path(path: Path):
+    """Returns true if path supplied is a valid path to a file or directory
+
+    Args:
+        path (pathlib.Path): pathlib.Path object of a file or directory
+
+    Returns:
+        bool: True if a valid path is supplied else False
+    """
+    path = Path(path)
+    return path.is_dir() or path.is_file()
+
+
+def get_caller_name() -> str:
+    """Utility function that uses the `inspect` module to access the call stack and returns the name
+    of the function that is two levels above in the stack. This is typically the function
+    that called the function that invoked `get_caller_name`.
+
+    Ex: start_matlab() -> set_matlab_state() -> get_caller_name()
+    The return value from get_caller_name() would be `start_matlab`
+
+    Returns:
+        str: Name of the parent function.
+    """
+    try:
+        return inspect.stack()[2][3]
+
+    except Exception as err:
+        logger.error(f"Failed to get caller name with err:{err}")
+        stack = inspect.stack()
+        return stack[len(stack) - 1][3]
+
+
+class TrackingLock:
+    """A class which provides the same features as asyncio.Lock
+    and additionally tracks which function acquired the lock.
+    """
+
+    def __init__(self, purpose):
+        self._acquired_by = None
+        self._lock = asyncio.Lock()
+        if not purpose:
+            logger.warning("Provide a purpose for this instance of TrackingLock")
+        self._purpose = purpose
+
+    @property
+    def acquired_by(self):
+        return self._acquired_by
+
+    @property
+    def purpose(self):
+        return self._purpose
+
+    def locked(self):
+        return self._lock.locked()
+
+    async def acquire(self):
+        """Acquires the lock"""
+        await self._lock.acquire()
+        # Store the current task or function information when the lock is acquired
+        self._acquired_by = get_caller_name()
+        logger.debug(f"Lock acquired by '{self.acquired_by}()'")
+
+    async def release(self):
+        """Releases the lock."""
+        if self.locked():
+            # Clear the owner information when the lock is released
+            self._lock.release()
+            logger.debug(f"Lock released by '{self.acquired_by}()'")
+            self._acquired_by = None
+
+        else:
+            logger.warn(f"Trying to release {self._purpose} lock before acquiring it.")
+
+    def validate_lock_for_caller(self, caller):
+        """Checks if the specified caller is the current holder of the lock.
+
+        This method first verifies that the lock is currently held. If it is,
+        it then compares the holder's name with the provided caller's name
+        to ensure they match.
+
+        This function should be used by setter methods for verification, before they modify critical sections.
+
+        Args:
+        caller (str): The name of the function to be matched with the lock holder.
+
+        Returns:
+            bool: True if the caller currently holds the lock, False otherwise.
+        """
+        if not self._lock.locked():
+            logger.error(
+                LockAcquisitionError(
+                    f"Lock needs to be acquired by '{caller}()' before modifying {self._purpose}"
+                )
+            )
+            return False
+
+        if self._acquired_by != caller:
+            logger.error(
+                LockAcquisitionError(
+                    f"Lock was acquired by {self._acquired_by} but {self._purpose} is being modified by {caller}."
+                )
+            )
+            return False
+
+        return True

matlab_proxy/util/cookie_jar.py

@@ -0,0 +1,72 @@
+# Copyright 2025 The MathWorks, Inc.
+
+from http.cookies import Morsel, SimpleCookie
+from typing import Dict
+
+from matlab_proxy.util import mwi
+
+logger = mwi.logger.get()
+
+
+# For more information about HttpOnly attribute
+# of a cookie, check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#httponly
+class HttpOnlyCookieJar:
+    """
+    A lightweight, HttpOnly, in-memory cookie store.
+
+    Its sole responsibility is to parse and store 'Set-Cookie' headers as Morsel objects and
+    store them in the cookie-jar only if they are marked as HttpOnly.
+    """
+
+    def __init__(self):
+        self._cookie_jar: Dict[str, Morsel] = {}
+        logger.debug("Cookie Jar Initialized")
+
+    def _get_cookie_name(self, cookie: SimpleCookie) -> str:
+        """
+        Returns the name of the cookie.
+        """
+        return list(cookie.keys())[0]
+
+    def update_from_response_headers(self, headers) -> None:
+        """
+        Parses 'Set-Cookie' headers from a response and stores the resulting
+        cookie objects (Morsels) only if they are HttpOnly cookies.
+        """
+        for set_cookie_val in headers.getall("Set-Cookie", []):
+            cookie = SimpleCookie()
+            cookie.load(set_cookie_val)
+            cookie_name = self._get_cookie_name(cookie)
+            morsel = cookie[cookie_name]
+
+            if morsel["httponly"]:
+                self._cookie_jar[cookie_name] = morsel
+                logger.debug(
+                    f"Stored cookie object for key '{cookie_name}'. Value: '{cookie[cookie_name]}'"
+                )
+
+            else:
+                logger.warning(
+                    f"Cookie {cookie_name} is not a HttpOnly cookie. Skipping it."
+                )
+
+    def get_cookies(self):
+        """
+        Returns a copy of the internal dictionary of stored cookie Morsels.
+        """
+        return list(self._cookie_jar.values())
+
+    def get_dict(self) -> Dict[str, str]:
+        """
+        Returns the stored cookies as a simple dictionary of name-to-value strings,
+        which is compatible with aiohttp's 'LooseCookies' type.
+        """
+        loose_cookies = {
+            name: morsel.value for name, morsel in self._cookie_jar.items()
+        }
+        return loose_cookies
+
+    def clear(self):
+        """Clears all stored cookies."""
+        logger.info("Cookie Jar Cleared")
+        self._cookie_jar.clear()

matlab_proxy/util/event_loop.py

@@ -1,8 +1,10 @@
-# Copyright 2020-2022 The MathWorks, Inc.
+# Copyright 2020-2024 The MathWorks, Inc.
+
+from typing import Dict, Set, Union
+from contextlib import suppress
 
 import asyncio
 
-from matlab_proxy import util
 from matlab_proxy.util import mwi, system, windows
 
 logger = mwi.logger.get()
@@ -30,16 +32,32 @@ def get_event_loop():
     return loop
 
 
-async def cancel_tasks(tasks):
+async def cancel_tasks(tasks: Union[Dict[str, asyncio.Task], Set[asyncio.Task]]):
     """Cancels asyncio tasks.
 
     Args:
-        tasks (asyncio.Task): Asyncio task
+        tasks: If a Dict[str, asyncio.Task], contains (task_name, task) as entries.
+               If a Set[asyncio.Task], contains a set of asyncio.Task objects.
+    """
+    if isinstance(tasks, dict):
+        for name, task in list(tasks.items()):
+            if task:
+                await __cancel_task(task)
+                logger.debug(f"{name} task stopped successfully")
+
+    elif isinstance(tasks, set):
+        for task in tasks:
+            if task:
+                await __cancel_task(task)
+                logger.debug(f"Task stopped successfully")
+
+
+async def __cancel_task(task):
+    """Cancels a given asyncio task, suppressing CancelledError.
+
+    Args:
+        task (asyncio.Task): The asyncio task to be cancelled.
     """
-    for task in tasks:
-        logger.debug(f"Calling cancel on task: {task}")
+    with suppress(asyncio.CancelledError):
         task.cancel()
-        try:
-            await task
-        except asyncio.CancelledError:
-            pass
+        await task

matlab_proxy/util/list_servers.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2022 The MathWorks, Inc.
+# Copyright (c) 2020-2025 The MathWorks, Inc.
 # Script to print information about all running matlab-proxy servers for current user on current machine.
 
 import glob
@@ -7,6 +7,66 @@ import os
 import matlab_proxy.settings as mwi_settings
 import matlab_proxy.util as mwi_util
 
+from datetime import datetime
+from rich.console import Console
+from rich.table import Table
+
+__NO_SERVERS_MSG = "No MATLAB-PROXY Servers are currently running."
+
+
+def _extract_version_and_session(title):
+    """Extracts session name and MATLAB version from the title."""
+    parts = title.split("-")
+    if len(parts) < 2:
+        return title.replace("MATLAB ", ""), ""
+    session_name = parts[0].strip()
+    matlab_version = parts[1].strip().replace("MATLAB ", "")
+    return matlab_version, session_name
+
+
+def _get_server_info(server):
+    """Helper function to parse info from server file."""
+    with open(server) as f:
+        # Assumes that the server file contains the address on the first line,
+        # the browser_title on the second line, and the timestamp is derived from the file's last modified time.
+        address = f.readline().strip()
+        browser_title = f.readline().strip()
+        matlab_version, session_name = _extract_version_and_session(browser_title)
+        timestamp = _get_timestamp(server)
+        return timestamp, matlab_version, session_name, address
+
+
+def _print_server_info_as_table(servers):
+    console = Console()
+    table = Table(
+        title="MATLAB Proxy Servers",
+        title_style="cyan",
+        title_justify="center",
+        caption="No servers found." if not servers else "",
+        caption_style="bold red",
+        show_header=True,
+        header_style="yellow",
+        show_lines=True,
+        show_edge=True,
+    )
+    table.add_column("Created On")
+    table.add_column("MATLAB\nVersion")
+    table.add_column("Session Name")
+    table.add_column("Server URL", overflow="fold")
+
+    # Build server information
+    for server in servers:
+        table.add_row(*_get_server_info(server))
+
+    console.print(table)
+
+
+def _get_timestamp(filename):
+    """Get the last modified timestamp of the file in a human-readable format."""
+    timestamp = os.path.getmtime(filename)
+    readable_time = datetime.fromtimestamp(timestamp).strftime("%d/%m/%y %H:%M:%S")
+    return readable_time
+
 
 def print_server_info():
     """Print information about all matlab-proxy servers (with version > 0.4.0) running on this machine"""
@@ -15,30 +75,15 @@ def print_server_info():
     # Look for files in port folders
     ports_folder = home_folder / "ports"
     search_string = str(ports_folder) + "/**/mwi_server.info"
+    servers = sorted(glob.glob(search_string), key=os.path.getmtime)
 
-    print_output = str(
-        mwi_util.prettify(
-            boundary_filler="-",
-            text_arr=["Your running servers are:"],
-        )
-    )
-    print_output += "\n"
-    search_results = sorted(glob.glob(search_string), key=os.path.getmtime)
-    if len(search_results) == 0:
-        print_output += "No MATLAB-PROXY Servers are currently running."
-    else:
-        server_number = 0
-        for server in search_results:
-            server_number += 1
-            with open(server) as f:
-                server_info = f.read()
-                print_output += str(server_number) + ".  " + str(server_info)
-
-    print_output += str(
-        mwi_util.prettify(
-            boundary_filler="-",
-            text_arr=["Thank you."],
-        )
-    )
+    args = mwi_util.parse_list_cli_args()
 
-    return print_output
+    if args["quiet"]:
+        for server in servers:
+            with open(server) as f:
+                server_info = f.readline().strip()
+                print(f"{server_info}", end="\n")
+    else:
+        _print_server_info_as_table(servers)
+    return

matlab_proxy/util/mw.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2022 The MathWorks, Inc.
+# Copyright 2020-2024 The MathWorks, Inc.
 
 import asyncio
 import os
@@ -8,6 +8,7 @@ import xml.etree.ElementTree as ET
 import aiohttp
 from matlab_proxy.default_configuration import config
 from matlab_proxy.util import mwi
+from matlab_proxy.settings import get_process_startup_timeout
 from matlab_proxy.util.mwi.exceptions import (
     EntitlementError,
     MatlabError,
@@ -45,7 +46,7 @@ async def fetch_entitlements(mhlm_api_endpoint, access_token, matlab_release):
         list: Representing a list of Dicts containing the id, label and license_number.
     """
     # Get entitlements for token
-    async with aiohttp.ClientSession() as client_session:
+    async with aiohttp.ClientSession(trust_env=True) as client_session:
         async with client_session.post(
             mhlm_api_endpoint,
             headers={"content-type": "application/x-www-form-urlencoded"},
@@ -59,8 +60,7 @@ async def fetch_entitlements(mhlm_api_endpoint, access_token, matlab_release):
                 }
             ),
         ) as res:
-
-            if res.reason != "OK":
+            if not res.ok:
                 raise OnlineLicensingError(
                     f"Communication with {mhlm_api_endpoint} failed ({res.status}). For more details, see {__get_licensing_url()}."
                 )
@@ -70,7 +70,7 @@ async def fetch_entitlements(mhlm_api_endpoint, access_token, matlab_release):
 
             if entitlement_el is None or len(entitlement_el) == 0:
                 raise EntitlementError(
-                    f"Your MathWorks account is not linked to a valid license for MATLAB {matlab_release}."
+                    f"Your MathWorks account is not linked to a valid license for MATLAB {matlab_release}.\nSign out and login with a licensed user."
                 )
 
             entitlements = entitlement_el.findall("entitlement")
@@ -86,7 +86,7 @@ async def fetch_entitlements(mhlm_api_endpoint, access_token, matlab_release):
 
 
 async def fetch_expand_token(mwa_api_endpoint, identity_token, source_id):
-    """Asynchronously fetch tokens from MWA API after MHLM licensing is successful.
+    """Asynchronously fetch tokens from MWA API endpoint.
 
     Args:
         mwa_api_endpoint (String): URL of the MWA API endpoint.
@@ -99,7 +99,7 @@ async def fetch_expand_token(mwa_api_endpoint, identity_token, source_id):
     Returns:
         Dict: Containing User and License expiration details.
     """
-    async with aiohttp.ClientSession() as client_session:
+    async with aiohttp.ClientSession(trust_env=True) as client_session:
         async with client_session.post(
             f"{mwa_api_endpoint}/tokens",
             headers={
@@ -115,8 +115,7 @@ async def fetch_expand_token(mwa_api_endpoint, identity_token, source_id):
                 }
             ),
         ) as res:
-
-            if res.reason != "OK":
+            if not res.ok:
                 raise OnlineLicensingError(
                     f"Communication with {mwa_api_endpoint} failed ({res.status}). For more details, see {__get_licensing_url()}."
                 )
@@ -147,7 +146,7 @@ async def fetch_access_token(mwa_api_endpoint, identity_token, source_id):
     Returns:
         Dict : Containing the Access token.
     """
-    async with aiohttp.ClientSession() as client_session:
+    async with aiohttp.ClientSession(trust_env=True) as client_session:
         async with client_session.post(
             f"{mwa_api_endpoint}/tokens/access",
             headers={
@@ -163,8 +162,7 @@ async def fetch_access_token(mwa_api_endpoint, identity_token, source_id):
                 }
             ),
         ) as res:
-
-            if res.reason != "OK":
+            if not res.ok:
                 raise OnlineLicensingError(
                     f"Communication with {mwa_api_endpoint} failed ({res.status}). For more details, see {__get_licensing_url()}."
                 )
@@ -260,7 +258,7 @@ def parse_other_error(logs):
     )
 
 
-async def create_xvfb_process(xvfb_cmd, pipe, env={}):
+async def create_xvfb_process(xvfb_cmd, pipe, env=None):
     """Creates the Xvfb process.
 
     The Xvfb process is run with '-displayfd' flag set. This makes Xvfb choose an available
@@ -293,8 +291,11 @@ async def create_xvfb_process(xvfb_cmd, pipe, env={}):
     number_of_bytes = 200
 
     logger.debug("Waiting for XVFB process to initialize and provide Display Number")
-    # Waits upto 10 seconds for the read_descriptor to be ready.
-    ready_descriptors, _, _ = select.select([read_descriptor], [], [], 10)
+
+    # Wait for timeout specified by matlab-proxy for launching processes.
+    ready_descriptors, _, _ = select.select(
+        [read_descriptor], [], [], get_process_startup_timeout()
+    )
 
     # If read_descriptor is in ready_descriptors, read from it.
     if read_descriptor in ready_descriptors: