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

matlab_proxy_manager/storage/server.py

@@ -0,0 +1,172 @@
+# Copyright 2024-2025 The MathWorks, Inc.
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import psutil
+
+from matlab_proxy_manager.utils import helpers, logger
+
+log = logger.get()
+
+
+@dataclass
+class ServerProcess:
+    """
+    Represents a MATLAB server process with various attributes and methods
+    to manage its lifecycle.
+    """
+
+    server_url: Optional[str] = None
+    mwi_base_url: Optional[str] = None
+    headers: Optional[dict] = None
+    errors: Optional[list] = None
+    pid: Optional[str] = None
+    parent_pid: Optional[str] = None
+    absolute_url: Optional[str] = field(default=None)
+    id: Optional[str] = None
+    type: Optional[str] = None
+    mpm_auth_token: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if not self.absolute_url:
+            self.absolute_url = f"{self.server_url}{self.mwi_base_url}"
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the ServerProcess instance.
+        """
+        return json.dumps(asdict(self))
+
+    def as_dict(self) -> dict:
+        """
+        Returns a dict representation of the ServerProcess instance.
+        """
+        return asdict(self)
+
+    @staticmethod
+    def instantiate_from_string(data: str) -> "ServerProcess":
+        """
+        Instantiates a ServerProcess object from a JSON string.
+
+        Args:
+            data (str): The JSON string representing a ServerProcess.
+
+        Returns:
+            ServerProcess: An instance of ServerProcess.
+
+        Raises:
+            ValueError: If the JSON string cannot be parsed or is missing required fields.
+        """
+        try:
+            full_dict = json.loads(data)
+            key = list(full_dict.keys())[0]
+            server = full_dict[key]
+            server_process = ServerProcess(
+                server_url=server["server_url"],
+                mwi_base_url=server["mwi_base_url"],
+                headers=server["headers"],
+                errors=server["errors"],
+                pid=server["pid"],
+                parent_pid=server["parent_pid"],
+                absolute_url=server["absolute_url"],
+                id=server["id"],
+                type=server["type"],
+                mpm_auth_token=server["mpm_auth_token"],
+            )
+            return server_process
+        except (json.JSONDecodeError, KeyError) as ex:
+            log.debug("Failed to instantiate server from %s: %s", data, ex)
+            raise ValueError(
+                "Invalid JSON string for ServerProcess instantiation"
+            ) from ex
+
+    def shutdown(self):
+        """
+        Shuts down the MATLAB proxy server by calling the shutdown_integration endpoint.
+        """
+        log.debug("Shutting down matlab proxy")
+        backend_server = self.absolute_url
+        url = f"{backend_server}/shutdown_integration"
+        try:
+            response = helpers.requests_retry_session(retries=1).delete(
+                url=url, headers=self.headers
+            )
+            shutdown_resp = response.json()
+            log.debug("Response from shutdown: %s", response.json())
+            return shutdown_resp
+        except Exception as e:
+            log.debug("Exception while shutting down matlab proxy: %s", e)
+
+            # Force kill matlab-proxy and its process tree if termination
+            # via shutdown_integration endpoint fails
+            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):
+        """
+        Terminates the process tree of the MATLAB proxy server.
+
+        This method terminates all child processes of the MATLAB proxy process,
+        waits for a short period, and then forcefully kills any remaining processes.
+        Finally, it kills the main MATLAB proxy process itself.
+        """
+        matlab_proxy_child_processes = matlab_proxy_process.children(recursive=True)
+        for child_process in matlab_proxy_child_processes:
+            child_process.terminate()
+        _, alive = psutil.wait_procs(matlab_proxy_child_processes, timeout=5)
+        for process in alive:
+            # Kill the processes which are alive even after waiting for 5 seconds
+            process.kill()
+        matlab_proxy_process.kill()
+        log.debug("Killed matlab-proxy process with PID: %s", self.pid)
+
+    def is_server_alive(self) -> bool:
+        """
+        Checks if the server process is alive and ready.
+
+        Returns:
+            bool: True if the server process is alive and ready, False otherwise.
+        """
+        return helpers.does_process_exist(self.pid) and helpers.is_server_ready(
+            self.absolute_url, retries=0
+        )
+
+    @staticmethod
+    def find_existing_server(data_dir, key: str) -> Optional["ServerProcess"]:
+        """
+        Finds an existing server process by reading the server configuration from a file.
+
+        Args:
+            data_dir (str): The directory where server configuration files are stored.
+            key (str): The key corresponding to the specific server configuration.
+
+        Returns:
+            Optional[ServerProcess]: An instance of ServerProcess if a valid configuration is found,
+            otherwise None.
+        """
+        key_dir = Path(data_dir, key)
+        server_process = None
+
+        # Return early if the directory is not found
+        if not key_dir.is_dir():
+            return server_process
+
+        files = list(key_dir.iterdir())
+        if not files:
+            return server_process
+
+        try:
+            with open(files[0], "r", encoding="utf-8") as file:
+                data = file.read().strip()
+                if data:
+                    server_process = ServerProcess.instantiate_from_string(data)
+        except (OSError, ValueError) as ex:
+            log.debug("Exception while checking for existing server: %s", ex)
+
+        return server_process

matlab_proxy_manager/utils/__init__.py

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

matlab_proxy_manager/utils/auth.py

@@ -0,0 +1,77 @@
+# Copyright 2024 The MathWorks, Inc.
+from hmac import compare_digest
+
+from aiohttp import web
+
+from matlab_proxy_manager.utils import logger
+from matlab_proxy_manager.utils.constants import HEADER_MWI_MPM_AUTH_TOKEN
+
+log = logger.get()
+
+
+async def authenticate_request(request):
+    """Authenticates incoming request by verifying whether the expected token is in the request.
+
+    The MWI-MPM-AUTH-TOKEN must be present in the request's headers.
+
+    Returns True/False based on whether the request is authenticated.
+    """
+
+    log.debug("<======== Authenticate request: %s", request)
+    return await _is_valid_token_in_headers(request)
+
+
+def authenticate_access_decorator(endpoint):
+    """This decorator verifies that the request to an endpoint exposed by matlab-proxy-manager
+    contains the correct mpm auth token before servicing an endpoint."""
+
+    async def protect_endpoint(request):
+        """Passes request to the endpoint after validating the token
+
+        Args:
+            request (HTTPRequest) : Web Request to endpoint
+
+        Raises:
+            web.HTTPForbidden: Thrown when validation of token fails
+        """
+        if await authenticate_request(request):
+            # request is authentic, proceed to execute the endpoint
+            return await endpoint(request)
+        raise web.HTTPForbidden(reason="Unauthorized access!")
+
+    return protect_endpoint
+
+
+async def _is_valid_token_in_headers(request):
+    """Checks the request headers for mpm auth token
+
+    Args:
+        request (HTTPRequest) : Used to access app settings
+
+    Returns:
+        Boolean : True if valid token is found, else False
+    """
+    headers = request.headers
+    if HEADER_MWI_MPM_AUTH_TOKEN in headers:
+        return await _is_valid_token(headers[HEADER_MWI_MPM_AUTH_TOKEN], request)
+
+    log.debug("Header: %s not found in request headers", HEADER_MWI_MPM_AUTH_TOKEN)
+    return False
+
+
+async def _is_valid_token(token, request):
+    """Checks if token contains expected value.
+
+    Args:
+        token (str): Token string to validate
+        request (HTTPRequest) : Used to access app settings
+
+    Returns:
+        _type_: True if token is valid, false otherwise.
+    """
+    # Check if the token provided in the request matches the original token
+    # equivalent to a == b, but protects against timing attacks
+    saved_token = request.app["auth_token"]
+    is_valid = compare_digest(token, saved_token)
+    log.debug("Token validation %s ", "successful." if is_valid else "failed.")
+    return is_valid

matlab_proxy_manager/utils/constants.py

@@ -0,0 +1,8 @@
+# Copyright 2024-2025 The MathWorks, Inc.
+import re
+
+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_IN_REQ_PATH_PATTERN = re.compile(r".*?/matlab/([^/]+)/(.*)")

matlab_proxy_manager/utils/decorators.py

@@ -0,0 +1,37 @@
+# Copyright 2025 The MathWorks, Inc.
+
+import functools
+from typing import Callable
+
+from matlab_proxy_manager.utils.constants import (
+    HEADER_MWI_MPM_CONTEXT,
+)
+from matlab_proxy_manager.utils.helpers import render_error_page
+
+
+def validate_incoming_request_decorator(endpoint: Callable):
+    """Decorator to validate incoming requests.
+
+    This decorator checks if the request contains the required MWI_MPM_CONTEXT header.
+    If the header is not found, it returns an error page. Otherwise, it adds the context
+    to the request object and proceeds with the endpoint execution.
+
+    Args:
+        endpoint (Callable): The endpoint function to be decorated.
+
+    Returns:
+        Callable: The wrapped function that validates the request before calling the endpoint.
+    """
+
+    @functools.wraps(endpoint)
+    async def wrapper(req):
+        ctx = req.headers.get(HEADER_MWI_MPM_CONTEXT)
+        if not ctx:
+            return render_error_page(
+                f"Required header: ${HEADER_MWI_MPM_CONTEXT} not found in the request"
+            )
+        # Add ctx to the request object
+        req.ctx = ctx
+        return await endpoint(req)
+
+    return wrapper

matlab_proxy_manager/utils/environment_variables.py

@@ -0,0 +1,51 @@
+# Copyright 2020-2025 The MathWorks, Inc.
+"""This file lists and exposes the environment variables which are used by proxy manager."""
+
+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 environment variable's value matches(case-insensitive) the string "True"
+    """
+    return os.environ.get(env_name, "").lower() == "true"
+
+
+def get_env_name_logging_level():
+    """Specifies the logging level used by app's loggers"""
+    return "MWI_MPM_LOG_LEVEL"
+
+
+def get_env_name_enable_web_logging():
+    """Enable the logging of asyncio web traffic by setting to true"""
+    return "MWI_MPM_ENABLE_WEB_LOGGING"
+
+
+def get_env_name_mwi_mpm_auth_token():
+    """Authentication environment variable for authenticating with proxy manager"""
+    return "MWI_MPM_AUTH_TOKEN"
+
+
+def get_env_name_mwi_mpm_port():
+    """Used to specify the port on which to start proxy manager"""
+    return "MWI_MPM_PORT"
+
+
+def get_env_name_mwi_mpm_parent_pid():
+    """Used to specify the parent pid for the proxy manager process"""
+    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
+        )