matlab-proxy 0.19.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

matlab_proxy_manager/storage/file_repository.py

@@ -0,0 +1,144 @@
+# Copyright 2024 The MathWorks, Inc.
+import glob
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+from matlab_proxy_manager.utils import logger
+
+from .interface import IRepository
+
+log = logger.get()
+
+
+class FileRepository(IRepository):
+    """
+    A repository for managing MATLAB proxy server processes using the file system.
+    """
+
+    def __init__(self, data_dir) -> None:
+        super().__init__()
+        self.data_dir = data_dir
+        self.encoding = "utf-8"
+
+    def get_all(self):
+        """Retrieves all server processes from the repository.
+
+        Returns:
+            A dictionary mapping file paths to server process instances.
+        """
+        from matlab_proxy_manager.storage.server import ServerProcess
+
+        servers = {}
+
+        # Read all the files in data_dir
+        all_files = glob.glob(f"{self.data_dir}/**/*.info", recursive=True)
+
+        for file in all_files:
+            try:
+                with open(file, "r", encoding=self.encoding) as f:
+                    data = f.read().strip()
+
+                    # Convert the content of each file to ServerProcess
+                    if data:
+                        server_process = ServerProcess.instantiate_from_string(data)
+                        servers[file] = server_process
+            except Exception as ex:
+                log.debug("ServerProcess instantiation failed for %s: %s", file, ex)
+        return servers
+
+    def get(self, name) -> tuple:
+        """
+        Retrieves a server process from the repository by its filename.
+
+        Args:
+            name (str): The name of the server process file.
+
+        Returns:
+            Tuple[Optional[str], Optional[ServerProcess]]: A tuple containing the file path
+            and the server process instance.
+        """
+        from matlab_proxy_manager.storage.server import ServerProcess
+
+        server_process = None
+        full_file_path: Optional[str] = None
+        current_files = glob.glob(f"{self.data_dir}/**/{name}.info", recursive=True)
+        if current_files:
+            full_file_path = current_files[0]
+            with open(full_file_path, "r", encoding=self.encoding) as f:
+                try:
+                    data = f.read().strip()
+                    if data:
+                        server_process = ServerProcess.instantiate_from_string(data)
+                except Exception as ex:
+                    log.debug(
+                        "ServerProcess instantiation failed for %s: %s",
+                        full_file_path,
+                        ex,
+                    )
+
+        return full_file_path, server_process
+
+    def add(self, server, filename: str) -> None:
+        """
+        Adds a server process to the repository.
+        Creates a directory like <ctx>_default|<kernel_id> and then creates a file as
+        default|<kernel_id>.info in that dir
+
+        Args:
+            server (ServerProcess): The server process instance to add.
+            filename (str): The filename to associate with the server process.
+        """
+        # Creates a child dir under the data_dir
+        server_dir = Path(f"{self.data_dir}", f"{server.id}")
+        Path.mkdir(server_dir, parents=True, exist_ok=True)
+        server_dict = {}
+
+        server_file = Path(server_dir, f"{filename}.info")
+        with open(server_file, "w", encoding=self.encoding) as f:
+            server_dict[server.id] = server.as_dict()
+            file_content = json.dumps(server_dict)
+            f.write(file_content)
+
+    def delete(self, filename: str) -> None:
+        """
+        Deletes a server process from the repository by its filename.
+
+        Args:
+            filename (str): The filename associated with the server process to delete.
+        """
+        # <path to proxy manager dir>/<parent_pid>_<name>/<name>.info
+        full_file_path, parent_dir = FileRepository._find_file_and_get_parent(
+            self.data_dir, filename
+        )
+        if full_file_path:
+            Path(full_file_path).unlink(missing_ok=True)
+            log.debug("Deleted file: %s", filename)
+
+            # delete the sub-directory (<parent_pid>_<id>) only if it is empty
+            if parent_dir and not len(os.listdir(parent_dir)):
+                os.rmdir(parent_dir)
+                log.debug("Deleted dir: %s", parent_dir)
+
+    @staticmethod
+    def _find_file_and_get_parent(data_dir: str, filename: str):
+        """
+        Finds the file and its parent directory in the given data directory.
+
+        Args:
+            data_dir (str): The base directory to search within.
+            filename (str): The filename to search for.
+
+        Returns:
+            Tuple[Optional[str], Optional[str]]: A tuple containing the full file path and the parent directory.
+        """
+        for dirpath, _, filenames in os.walk(data_dir):
+            # Check if target file is in the current directory's files
+            if filename in filenames:
+                full_path = os.path.join(dirpath, filename)
+                parent_dir = os.path.dirname(full_path)
+                return full_path, parent_dir
+
+        # Return None if the file was not found
+        return None, None

matlab_proxy_manager/storage/interface.py

@@ -0,0 +1,62 @@
+# Copyright 2024 The MathWorks, Inc.
+from typing import Protocol
+
+
+class IRepository(Protocol):
+    """
+    Protocol for a repository that manages MATLAB proxy server processes.
+    This protocol defines the required methods for adding, retrieving, and deleting
+    server process instances to the storage system (files).
+    """
+
+    def add(self, server, filename: str):
+        """
+        Adds a server process to the repository.
+
+        Args:
+            server (server.ServerProcess): The server process instance to add.
+            filename (str): The filename to associate with the server process.
+
+        Raises:
+            NotImplementedError
+        """
+        raise NotImplementedError("add not implemented")
+
+    def get(self, name: str) -> tuple:
+        """
+        Retrieves a server process from the repository by its filename.
+
+        Args:
+            filename (str): The filename associated with the server process.
+
+        Returns:
+            tuple (str, server.ServerProcess): Full file path and the retrieved server process instance.
+
+        Raises:
+            NotImplementedError
+        """
+        raise NotImplementedError("get not implemented")
+
+    def get_all(self):
+        """
+        Retrieves all server processes from the repository.
+
+        Returns:
+            Dict[str, server.ServerProcess]: Dict with filename as key and corresponding server process as value.
+
+        Raises:
+            NotImplementedError
+        """
+        raise NotImplementedError("get_all not implemented")
+
+    def delete(self, filename: str) -> None:
+        """
+        Deletes a server process from the repository by its filename.
+
+        Args:
+            filename (str): The filename associated with the server process to delete.
+
+        Raises:
+            NotImplementedError
+        """
+        raise NotImplementedError("delete not implemented")

matlab_proxy_manager/storage/server.py

@@ -0,0 +1,144 @@
+# Copyright 2024 The MathWorks, Inc.
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Optional
+
+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[int] = None
+    parent_pid: Optional[int] = 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)
+            return None
+
+    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,5 @@
+# Copyright 2024 The MathWorks, Inc.
+
+MWI_BASE_URL_PREFIX = "/matlab/"
+HEADER_MWI_MPM_CONTEXT = "MWI-MPM-CONTEXT"
+HEADER_MWI_MPM_AUTH_TOKEN = "MWI-MPM-AUTH-TOKEN"

matlab_proxy_manager/utils/environment_variables.py

@@ -0,0 +1,46 @@
+# Copyright 2020-2024 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 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())