appmesh 1.3.7__py3-none-any.whl → 1.3.8__py3-none-any.whl

appmesh/appmesh_client.py

@@ -1,1223 +1,8 @@
-"""App Mesh Python SDK"""
+# appmesh_client.py
 
-# pylint: disable=broad-exception-raised,line-too-long,broad-exception-caught,too-many-lines, import-outside-toplevel, protected-access
+# Legacy Compatibility Layer
+# These imports provide backward compatibility for older code that relies on
+# AppMeshClient, App, and AppOutput classes. The updated implementation can be found
+# in http_client.py, where these classes are now primarily maintained.
 
-# Standard library imports
-import abc
-import base64
-import json
-import os
-from datetime import datetime
-from enum import Enum, unique
-from http import HTTPStatus
-from typing import Tuple, Union
-from urllib import parse
-
-# Third-party imports
-import aniso8601
-import requests
-
-# Local application-specific imports
-from .app import App
-from .app_run import AppRun
-from .app_output import AppOutput
-
-
-class AppMeshClient(metaclass=abc.ABCMeta):
-    """
-    Client SDK for interacting with the App Mesh service via REST API.
-
-    The `AppMeshClient` class provides a comprehensive interface for managing and monitoring distributed applications
-    within the App Mesh ecosystem. It enables communication with the App Mesh REST API for operations such as
-    application lifecycle management, monitoring, and configuration.
-
-    This client is designed for direct usage in applications that require access to App Mesh services over HTTP-based REST.
-
-    Usage:
-        - Install the App Mesh Python package:
-            python3 -m pip install --upgrade appmesh
-        - Import the client module:
-            from appmesh import appmesh_client
-
-    Example:
-        client = appmesh_client.AppMeshClient()
-        client.login("your-name", "your-password")
-        response = client.app_view(app_name='ping')
-
-    Attributes:
-        - TLS (Transport Layer Security): Supports secure connections between the client and App Mesh service,
-          ensuring encrypted communication.
-        - JWT (JSON Web Token) and RBAC (Role-Based Access Control): Provides secure API access with
-          token-based authentication and authorization to enforce fine-grained permissions.
-
-    Methods:
-        # Authentication Management
-        - login()
-        - logoff()
-        - authentication()
-        - renew()
-        - totp_disable()
-        - totp_secret()
-        - totp_setup()
-
-        # Application Management
-        - app_add()
-        - app_delete()
-        - app_disable()
-        - app_enable()
-        - app_health()
-        - app_output()
-        - app_view()
-        - app_view_all()
-
-        # Run Application Operations
-        - run_async()
-        - run_async_wait()
-        - run_sync()
-
-        # System Management
-        - forwarding_host
-        - config_set()
-        - config_view()
-        - log_level_set()
-        - host_resource()
-        - metrics()
-        - tag_add()
-        - tag_delete()
-        - tag_view()
-
-        # File Management
-        - file_download()
-        - file_upload()
-
-        # User and Role Management
-        - user_add()
-        - user_delete()
-        - user_lock()
-        - user_passwd_update()
-        - user_self()
-        - user_unlock()
-        - users_view()
-        - permissions_for_user()
-        - permissions_view()
-        - role_delete()
-        - role_update()
-        - roles_view()
-        - groups_view()
-    """
-
-    DURATION_ONE_WEEK_ISO = "P1W"
-    DURATION_TWO_DAYS_ISO = "P2D"
-    DURATION_TWO_DAYS_HALF_ISO = "P2DT12H"
-
-    DEFAULT_SSL_CA_CERT_PATH = "/opt/appmesh/ssl/ca.pem"
-    DEFAULT_SSL_CLIENT_CERT_PATH = "/opt/appmesh/ssl/client.pem"
-    DEFAULT_SSL_CLIENT_KEY_PATH = "/opt/appmesh/ssl/client-key.pem"
-
-    JSON_KEY_MESSAGE = "message"
-    HTTP_USER_AGENT = "appmesh/python"
-    HTTP_HEADER_KEY_USER_AGENT = "User-Agent"
-    HTTP_HEADER_KEY_X_TARGET_HOST = "X-Target-Host"
-
-    @unique
-    class Method(Enum):
-        """REST methods"""
-
-        GET = "GET"
-        PUT = "PUT"
-        POST = "POST"
-        DELETE = "DELETE"
-        POST_STREAM = "POST_STREAM"
-
-    def __init__(
-        self,
-        rest_url: str = "https://127.0.0.1:6060",
-        rest_ssl_verify=DEFAULT_SSL_CA_CERT_PATH if os.path.exists(DEFAULT_SSL_CA_CERT_PATH) else False,
-        rest_ssl_client_cert=(DEFAULT_SSL_CLIENT_CERT_PATH, DEFAULT_SSL_CLIENT_KEY_PATH) if os.path.exists(DEFAULT_SSL_CLIENT_CERT_PATH) else None,
-        rest_timeout=(60, 300),
-        jwt_token=None,
-    ):
-        """Initialize an App Mesh HTTP client for interacting with the App Mesh server via secure HTTPS.
-
-        Args:
-            rest_url (str, optional): The server's base URI, including protocol, hostname, and port. Defaults to `"https://127.0.0.1:6060"`.
-
-            rest_ssl_verify (Union[bool, str], optional): Configures SSL certificate verification for HTTPS requests:
-                - `True`: Uses system CA certificates to verify the server's identity.
-                - `False`: Disables SSL verification (insecure, use cautiously for development).
-                - `str`: Path to a custom CA certificate or directory for verification. This option allows custom CA configuration,
-                which may be necessary in environments requiring specific CA chains that differ from the default system CAs.
-
-            rest_ssl_client_cert (Union[tuple, str], optional): Specifies a client certificate for mutual TLS authentication:
-                - If a `str`, provides the path to a PEM file with both client certificate and private key.
-                - If a `tuple`, contains two paths as (`cert`, `key`), where `cert` is the certificate file and `key` is the private key file.
-
-            rest_timeout (tuple, optional): HTTP connection timeouts for API requests, as `(connect_timeout, read_timeout)`.
-                The default is `(60, 300)`, where `60` seconds is the maximum time to establish a connection and `300` seconds for the maximum read duration.
-
-            jwt_token (str, optional): JWT token for API authentication, used in headers to authorize requests where required.
-
-        """
-
-        self.server_url = rest_url
-        self._jwt_token = jwt_token
-        self.ssl_verify = rest_ssl_verify
-        self.ssl_client_cert = rest_ssl_client_cert
-        self.rest_timeout = rest_timeout
-        self._forwarding_host = None
-
-    @property
-    def jwt_token(self) -> str:
-        """Get the current JWT (JSON Web Token) used for authentication.
-
-        This property manages the authentication token used for securing API requests.
-        The token is used to authenticate and authorize requests to the service.
-
-        Returns:
-            str: The current JWT token string.
-                Returns empty string if no token is set.
-
-        Notes:
-            - The token typically includes claims for identity and permissions
-            - Token format: "header.payload.signature"
-            - Tokens are time-sensitive and may expire
-        """
-        return self._jwt_token
-
-    @jwt_token.setter
-    def jwt_token(self, token: str) -> None:
-        """Set the JWT token for authentication.
-
-        Configure the JWT token used for authenticating requests. The token should be
-        a valid JWT issued by a trusted authority.
-
-        Args:
-            token (str): JWT token string in standard JWT format
-                (e.g., "eyJhbGci...payload...signature")
-                Pass empty string to clear the token.
-
-        Example:
-            >>> client.jwt_token = "eyJhbGci..."  # Set new token
-            >>> client.jwt_token = ""             # Clear token
-
-        Notes:
-            Security best practices:
-            - Store tokens securely
-            - Never log or expose complete tokens
-            - Refresh tokens before expiration
-            - Validate token format before setting
-        """
-        self._jwt_token = token
-
-    @property
-    def forwarding_host(self) -> str:
-        """Get the target host address for request forwarding in a cluster setup.
-
-        This property manages the destination host where requests will be forwarded to
-        within a cluster configuration. The host can be specified in two formats:
-        1. hostname/IP only: will use the current service's port
-        2. hostname/IP with port: will use the specified port
-
-        Returns:
-            str: The target host address in either format:
-                - "hostname" or "IP" (using current service port)
-                - "hostname:port" or "IP:port" (using specified port)
-                Returns empty string if no forwarding host is set.
-
-        Notes:
-            For proper JWT token sharing across the cluster:
-            - All nodes must share the same JWT salt configuration
-            - All nodes must use identical JWT issuer settings
-            - When port is omitted, current service port will be used
-        """
-        return self._forwarding_host
-
-    @forwarding_host.setter
-    def forwarding_host(self, host: str) -> None:
-        """Set the target host address for request forwarding.
-
-        Configure the destination host where requests should be forwarded to. This is
-        used in cluster setups for request routing and load distribution.
-
-        Args:
-            host (str): Target host address in one of two formats:
-                1. "hostname" or "IP" - will use current service port
-                (e.g., "backend-node" or "192.168.1.100")
-                2. "hostname:port" or "IP:port" - will use specified port
-                (e.g., "backend-node:6060" or "192.168.1.100:6060")
-                Pass empty string to disable forwarding.
-
-        Examples:
-            >>> client.forwarding_host = "backend-node:6060"  # Use specific port
-            >>> client.forwarding_host = "backend-node"       # Use current service port
-            >>> client.forwarding_host = None                 # Disable forwarding
-        """
-
-        self._forwarding_host = host
-
-    ########################################
-    # Security
-    ########################################
-    def login(self, user_name: str, user_pwd: str, totp_code="", timeout_seconds=DURATION_ONE_WEEK_ISO) -> str:
-        """Login with user name and password
-
-        Args:
-            user_name (str): the name of the user.
-            user_pwd (str): the password of the user.
-            totp_code (str, optional): the TOTP code if enabled for the user.
-            timeout_seconds (int | str, optional): token expire timeout of seconds. support ISO 8601 durations (e.g., 'P1Y2M3DT4H5M6S' 'P1W').
-
-        Returns:
-            str: JWT token.
-        """
-        self.jwt_token = None
-        resp = self._request_http(
-            AppMeshClient.Method.POST,
-            path="/appmesh/login",
-            header={
-                "Authorization": "Basic " + base64.b64encode((user_name + ":" + user_pwd).encode()).decode(),
-                "Expire-Seconds": self._parse_duration(timeout_seconds),
-            },
-        )
-        if resp.status_code == HTTPStatus.OK:
-            if "Access-Token" in resp.json():
-                self.jwt_token = resp.json()["Access-Token"]
-        elif resp.status_code == HTTPStatus.UNAUTHORIZED and "Totp-Challenge" in resp.json():
-            challenge = resp.json()["Totp-Challenge"]
-            resp = self._request_http(
-                AppMeshClient.Method.POST,
-                path="/appmesh/totp/validate",
-                header={
-                    "Username": base64.b64encode(user_name.encode()).decode(),
-                    "Totp-Challenge": base64.b64encode(challenge.encode()).decode(),
-                    "Totp": totp_code,
-                    "Expire-Seconds": self._parse_duration(timeout_seconds),
-                },
-            )
-            if resp.status_code == HTTPStatus.OK:
-                if "Access-Token" in resp.json():
-                    self.jwt_token = resp.json()["Access-Token"]
-            else:
-                raise Exception(resp.text)
-        else:
-            raise Exception(resp.text)
-        return self.jwt_token
-
-    def logoff(self) -> bool:
-        """Logoff current session from server
-
-        Returns:
-            bool: logoff success or failure.
-        """
-        resp = self._request_http(AppMeshClient.Method.POST, path="/appmesh/self/logoff")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        self.jwt_token = None
-        return resp.status_code == HTTPStatus.OK
-
-    def authentication(self, token: str, permission=None) -> bool:
-        """Login with token and verify permission when specified,
-           verified token will be stored in client object when success
-
-        Args:
-            token (str): JWT token returned from login().
-            permission (str, optional): the permission ID used to verify the token user
-                permission ID can be:
-                - pre-defined by App Mesh from security.yaml (e.g 'app-view', 'app-delete')
-                - defined by input from role_update() or security.yaml
-
-        Returns:
-            bool: authentication success or failure.
-        """
-        old_token = self.jwt_token
-        self.jwt_token = token
-        headers = {}
-        if permission:
-            headers["Auth-Permission"] = permission
-        resp = self._request_http(AppMeshClient.Method.POST, path="/appmesh/auth", header=headers)
-        if resp.status_code != HTTPStatus.OK:
-            self.jwt_token = old_token
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def renew(self, timeout_seconds=DURATION_ONE_WEEK_ISO) -> str:
-        """Renew current token
-
-        Args:
-            timeout_seconds (int | str, optional): token expire timeout of seconds. support ISO 8601 durations (e.g., 'P1Y2M3DT4H5M6S' 'P1W').
-
-        Returns:
-            str: The new JWT token if renew success, otherwise return None.
-        """
-        assert self.jwt_token
-        resp = self._request_http(
-            AppMeshClient.Method.POST,
-            path="/appmesh/token/renew",
-            header={
-                "Expire-Seconds": self._parse_duration(timeout_seconds),
-            },
-        )
-        if resp.status_code == HTTPStatus.OK:
-            if "Access-Token" in resp.json():
-                self.jwt_token = resp.json()["Access-Token"]
-                return self.jwt_token
-        raise Exception(resp.text)
-
-    def totp_secret(self) -> str:
-        """Generate TOTP secret for current login user and return MFA URI with JSON body
-
-        Returns:
-            str: TOTP secret str
-        """
-        resp = self._request_http(method=AppMeshClient.Method.POST, path="/appmesh/totp/secret")
-        if resp.status_code == HTTPStatus.OK:
-            totp_uri = base64.b64decode(resp.json()["Mfa-Uri"]).decode()
-            return self._parse_totp_uri(totp_uri).get("secret")
-        raise Exception(resp.text)
-
-    def totp_setup(self, totp_code: str) -> bool:
-        """Setup 2FA for current login user
-
-        Args:
-            totp_code (str): TOTP code
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(
-            method=AppMeshClient.Method.POST,
-            path="/appmesh/totp/setup",
-            header={"Totp": totp_code},
-        )
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def totp_disable(self, user="self") -> bool:
-        """Disable 2FA for current user
-
-        Args:
-            user (str, optional): user name for disable TOTP.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(
-            method=AppMeshClient.Method.POST,
-            path=f"/appmesh/totp/{user}/disable",
-        )
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    @staticmethod
-    def _parse_totp_uri(totp_uri: str) -> dict:
-        """Extract TOTP parameters
-
-        Args:
-            totp_uri (str): TOTP uri
-
-        Returns:
-            dict: eextract parameters
-        """
-        parsed_info = {}
-        parsed_uri = parse.urlparse(totp_uri)
-
-        # Extract label from the path
-        parsed_info["label"] = parsed_uri.path[1:]  # Remove the leading slash
-
-        # Extract parameters from the query string
-        query_params = parse.parse_qs(parsed_uri.query)
-        for key, value in query_params.items():
-            parsed_info[key] = value[0]
-        return parsed_info
-
-    ########################################
-    # Application view
-    ########################################
-    def app_view(self, app_name: str) -> App:
-        """Get one application information
-
-        Args:
-            app_name (str): the application name.
-
-        Returns:
-            App: the application object both contain static configuration and runtime information.
-
-        Exception:
-            failed request or no such application
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path=f"/appmesh/app/{app_name}")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return App(resp.json())
-
-    def app_view_all(self):
-        """Get all applications
-
-        Returns:
-            list: the application object both contain static configuration and runtime information, only return applications that the user has permissions.
-
-        Exception:
-            failed request or no such application
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path="/appmesh/applications")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        apps = []
-        for app in resp.json():
-            apps.append(App(app))
-        return apps
-
-    def app_output(self, app_name: str, stdout_position: int = 0, stdout_index: int = 0, stdout_maxsize: int = 10240, process_uuid: str = "", timeout: int = 0) -> AppOutput:
-        """Get application stdout/stderr
-
-        Args:
-            app_name (str): the application name
-            stdout_position (int, optional): start read position, 0 means start from beginning.
-            stdout_index (int, optional): index of history process stdout, 0 means get from current running process,
-                the stdout number depends on 'stdout_cache_size' of the application.
-            stdout_maxsize (int, optional): max buffer size to read.
-            process_uuid (str, optional): used to get the specified process.
-            timeout (int, optional): wait for the running process for some time(seconds) to get the output.
-
-        Returns:
-            AppOutput object.
-        """
-        resp = self._request_http(
-            AppMeshClient.Method.GET,
-            path=f"/appmesh/app/{app_name}/output",
-            query={
-                "stdout_position": str(stdout_position),
-                "stdout_index": str(stdout_index),
-                "stdout_maxsize": str(stdout_maxsize),
-                "process_uuid": process_uuid,
-                "timeout": str(timeout),
-            },
-        )
-        out_position = int(resp.headers["Output-Position"]) if "Output-Position" in resp.headers else None
-        exit_code = int(resp.headers["Exit-Code"]) if "Exit-Code" in resp.headers else None
-        return AppOutput(status_code=resp.status_code, output=resp.text, out_position=out_position, exit_code=exit_code)
-
-    def app_health(self, app_name: str) -> bool:
-        """Get application health status
-
-        Args:
-            app_name (str): the application name.
-
-        Returns:
-            bool: healthy or not
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path=f"/appmesh/app/{app_name}/health")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return int(resp.text) == 0
-
-    ########################################
-    # Application manage
-    ########################################
-    def app_add(self, app: App) -> App:
-        """Register an application
-
-        Args:
-            app (App): the application definition.
-
-        Returns:
-            App: resigtered application object.
-
-        Exception:
-            failed request
-        """
-        resp = self._request_http(AppMeshClient.Method.PUT, path=f"/appmesh/app/{app.name}", body=app.json())
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return App(resp.json())
-
-    def app_delete(self, app_name: str) -> bool:
-        """Remove an application.
-
-        Args:
-            app_name (str): the application name.
-
-        Returns:
-            bool: True for delete success, Flase for not exist anymore.
-        """
-        resp = self._request_http(AppMeshClient.Method.DELETE, path=f"/appmesh/app/{app_name}")
-        if resp.status_code == HTTPStatus.OK:
-            return True
-        elif resp.status_code == HTTPStatus.NOT_FOUND:
-            return False
-        else:
-            raise Exception(resp.text)
-
-    def app_enable(self, app_name: str) -> bool:
-        """Enable an application
-
-        Args:
-            app_name (str): the application name.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(AppMeshClient.Method.POST, path=f"/appmesh/app/{app_name}/enable")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def app_disable(self, app_name: str) -> bool:
-        """Stop and disable an application
-
-        Args:
-            app_name (str): the application name.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(AppMeshClient.Method.POST, path=f"/appmesh/app/{app_name}/disable")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    ########################################
-    # Cloud management
-    ########################################
-    def cloud_app_view_all(self) -> dict:
-        """Get all cloud applications
-
-        Returns:
-            dict: cloud applications in JSON format.
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path="/appmesh/cloud/applications")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def cloud_app(self, app_name: str) -> dict:
-        """Get an cloud application
-
-        Args:
-            app_name (str): the application name.
-
-        Returns:
-            dict: application in JSON format.
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path=f"/appmesh/cloud/app/{app_name}")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def cloud_app_output(self, app_name: str, host_name: str, stdout_position: int = 0, stdout_index: int = 0, stdout_maxsize: int = 10240, process_uuid: str = ""):
-        """Get cloud application stdout/stderr from master agent
-
-        Args:
-            app_name (str): the application name
-            host_name (str): the target host name where the application is running
-            stdout_position (int, optional): start read position, 0 means start from beginning.
-            stdout_index (int, optional): index of history process stdout, 0 means get from current running process,
-                the stdout number depends on 'stdout_cache_size' of the application.
-            stdout_maxsize (int, optional): max buffer size to read.
-            process_uuid (str, optional): used to get the specified process.
-
-        Returns:
-            bool: success or failure.
-            str: output string.
-            int or None: current read position.
-            int or None: process exit code.
-        """
-        resp = self._request_http(
-            AppMeshClient.Method.GET,
-            path=f"/appmesh/cloud/app/{app_name}/output/{host_name}",
-            query={
-                "stdout_position": str(stdout_position),
-                "stdout_index": str(stdout_index),
-                "stdout_maxsize": str(stdout_maxsize),
-                "process_uuid": process_uuid,
-            },
-        )
-        out_position = int(resp.headers["Output-Position"]) if "Output-Position" in resp.headers else None
-        exit_code = int(resp.headers["Exit-Code"]) if "Exit-Code" in resp.headers else None
-        return (resp.status_code == HTTPStatus.OK), resp.text, out_position, exit_code
-
-    def cloud_app_delete(self, app_name: str) -> bool:
-        """Delete a cloud application
-
-        Args:
-            app_name (str): The application name for cloud
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(AppMeshClient.Method.DELETE, path=f"/appmesh/cloud/app/{app_name}")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def cloud_app_add(self, app_json: dict) -> dict:
-        """Add a cloud application
-
-        Args:
-            app_json (dict): the cloud application definition with replication, condition and resource requirement
-
-         Returns:
-            dict: cluster application json.
-        """
-        resp = self._request_http(AppMeshClient.Method.PUT, path=f"/appmesh/cloud/app/{app_json['content']['name']}", body=app_json)
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def cloud_nodes(self) -> dict:
-        """Get cluster node list
-
-        Returns:
-            dict: cluster node list json.
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path="/appmesh/cloud/nodes")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    ########################################
-    # Configuration
-    ########################################
-    def host_resource(self) -> dict:
-        """Get App Mesh host resource report include CPU, memory and disk
-
-        Returns:
-            dict: the host resource json.
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path="/appmesh/resources")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def config_view(self) -> dict:
-        """Get App Mesh configuration JSON
-
-        Returns:
-            dict: the configuration json.
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path="/appmesh/config")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def config_set(self, cfg_json) -> dict:
-        """Update configuration, the format follow 'config.yaml', support partial update
-
-        Args:
-            cfg_json (dict): the new configuration json.
-
-        Returns:
-            dict: the updated configuration json.
-        """
-        resp = self._request_http(AppMeshClient.Method.POST, path="/appmesh/config", body=cfg_json)
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def log_level_set(self, level: str = "DEBUG") -> str:
-        """Update App Mesh log level(DEBUG/INFO/NOTICE/WARN/ERROR), a wrapper of config_set()
-
-        Args:
-            level (str, optional): log level.
-
-        Returns:
-            str: the updated log level.
-        """
-        resp = self._request_http(AppMeshClient.Method.POST, path="/appmesh/config", body={"BaseConfig": {"LogLevel": level}})
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()["BaseConfig"]["LogLevel"]
-
-    ########################################
-    # User Management
-    ########################################
-    def user_passwd_update(self, new_password: str, user_name: str = "self") -> bool:
-        """Change user password
-
-        Args:
-            user_name (str): the user name.
-            new_password (str):the new password string
-
-        Returns:
-            bool: success
-        """
-        resp = self._request_http(
-            method=AppMeshClient.Method.POST,
-            path=f"/appmesh/user/{user_name}/passwd",
-            header={"New-Password": base64.b64encode(new_password.encode())},
-        )
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return True
-
-    def user_add(self, user_name: str, user_json: dict) -> bool:
-        """Add a new user, not available for LDAP user
-
-        Args:
-            user_name (str): the user name.
-            user_json (dict): user definition, follow same user format from security.yaml.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(
-            method=AppMeshClient.Method.PUT,
-            path=f"/appmesh/user/{user_name}",
-            body=user_json,
-        )
-        return resp.status_code == HTTPStatus.OK
-
-    def user_delete(self, user_name: str) -> bool:
-        """Delete a user
-
-        Args:
-            user_name (str): the user name.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(
-            method=AppMeshClient.Method.DELETE,
-            path=f"/appmesh/user/{user_name}",
-        )
-        return resp.status_code == HTTPStatus.OK
-
-    def user_lock(self, user_name: str) -> bool:
-        """Lock a user
-
-        Args:
-            user_name (str): the user name.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(
-            method=AppMeshClient.Method.POST,
-            path=f"/appmesh/user/{user_name}/lock",
-        )
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def user_unlock(self, user_name: str) -> bool:
-        """Unlock a user
-
-        Args:
-            user_name (str): the user name.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(
-            method=AppMeshClient.Method.POST,
-            path=f"/appmesh/user/{user_name}/unlock",
-        )
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def users_view(self) -> dict:
-        """Get all users
-
-        Returns:
-            dict: all user definition
-        """
-        resp = self._request_http(method=AppMeshClient.Method.GET, path="/appmesh/users")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def user_self(self) -> dict:
-        """Get current user infomation
-
-        Returns:
-            dict: user definition.
-        """
-        resp = self._request_http(method=AppMeshClient.Method.GET, path="/appmesh/user/self")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def groups_view(self) -> list:
-        """Get all user groups
-
-        Returns:
-            dict: user group array.
-        """
-        resp = self._request_http(method=AppMeshClient.Method.GET, path="/appmesh/user/groups")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def permissions_view(self) -> list:
-        """Get all available permissions
-
-        Returns:
-            dict: permission array
-        """
-        resp = self._request_http(method=AppMeshClient.Method.GET, path="/appmesh/permissions")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def permissions_for_user(self) -> list:
-        """Get current user permissions
-
-        Returns:
-            dict: user permission array.
-        """
-        resp = self._request_http(method=AppMeshClient.Method.GET, path="/appmesh/user/permissions")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def roles_view(self) -> list:
-        """Get all roles with permission definition
-
-        Returns:
-            dict: all role definition.
-        """
-        resp = self._request_http(method=AppMeshClient.Method.GET, path="/appmesh/roles")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    def role_update(self, role_name: str, role_permission_json: dict) -> bool:
-        """Update (or add) a role with defined permissions, the permission ID can be App Mesh pre-defined or other permission ID.
-
-        Args:
-            role_name (str): the role name.
-            role_permission_json (dict): role permission definition array, e.g: ["app-control", "app-delete", "cloud-app-reg", "cloud-app-delete"]
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(method=AppMeshClient.Method.POST, path=f"/appmesh/role/{role_name}", body=role_permission_json)
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def role_delete(self, role_name: str) -> bool:
-        """Delete a user role
-
-        Args:
-            role_name (str): the role name.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(
-            method=AppMeshClient.Method.DELETE,
-            path=f"/appmesh/role/{role_name}",
-        )
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    ########################################
-    # Tag management
-    ########################################
-    def tag_add(self, tag_name: str, tag_value: str) -> bool:
-        """Add a new label
-
-        Args:
-            tag_name (str): the label name.
-            tag_value (str): the label value.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(
-            AppMeshClient.Method.PUT,
-            query={"value": tag_value},
-            path=f"/appmesh/label/{tag_name}",
-        )
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def tag_delete(self, tag_name: str) -> bool:
-        """Delete a label
-
-        Args:
-            tag_name (str): the label name.
-
-        Returns:
-            bool: success or failure.
-        """
-        resp = self._request_http(AppMeshClient.Method.DELETE, path=f"/appmesh/label/{tag_name}")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.status_code == HTTPStatus.OK
-
-    def tag_view(self) -> dict:
-        """Get the server labels
-
-        Returns:
-            dict: label data.
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path="/appmesh/labels")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.json()
-
-    ########################################
-    # Promethus metrics
-    ########################################
-    def metrics(self):
-        """Prometheus metrics (this does not call Prometheus API /metrics, just copy the same metrics data)
-
-        Returns:
-            str: prometheus metrics texts
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path="/appmesh/metrics")
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-        return resp.text
-
-    ########################################
-    # File management
-    ########################################
-    def file_download(self, remote_file: str, local_file: str, apply_file_attributes: bool = True) -> None:
-        """Copy a remote file to local. Optionally, the local file will have the same permission as the remote file.
-
-        Args:
-            remote_file (str): the remote file path.
-            local_file (str): the local file path to be downloaded.
-            apply_file_attributes (bool): whether to apply file attributes (permissions, owner, group) to the local file.
-        """
-        resp = self._request_http(AppMeshClient.Method.GET, path="/appmesh/file/download", header={"File-Path": remote_file})
-        resp.raise_for_status()
-
-        # Write the file content locally
-        with open(local_file, "wb") as fp:
-            for chunk in resp.iter_content(chunk_size=8 * 1024):  # 8 KB
-                if chunk:
-                    fp.write(chunk)
-
-        # Apply file attributes (permissions, owner, group) if requested
-        if apply_file_attributes:
-            if "File-Mode" in resp.headers:
-                os.chmod(path=local_file, mode=int(resp.headers["File-Mode"]))
-            if "File-User" in resp.headers and "File-Group" in resp.headers:
-                file_uid = int(resp.headers["File-User"])
-                file_gid = int(resp.headers["File-Group"])
-                try:
-                    os.chown(path=local_file, uid=file_uid, gid=file_gid)
-                except PermissionError:
-                    print(f"Warning: Unable to change owner/group of {local_file}. Operation requires elevated privileges.")
-
-    def file_upload(self, local_file: str, remote_file: str, apply_file_attributes: bool = True) -> None:
-        """Upload a local file to the remote server. Optionally, the remote file will have the same permission as the local file.
-
-        Dependency:
-            sudo apt install python3-pip
-            pip3 install requests_toolbelt
-
-        Args:
-            local_file (str): the local file path.
-            remote_file (str): the target remote file to be uploaded.
-            apply_file_attributes (bool): whether to upload file attributes (permissions, owner, group) along with the file.
-        """
-        if not os.path.exists(local_file):
-            raise FileNotFoundError(f"Local file not found: {local_file}")
-
-        from requests_toolbelt import MultipartEncoder
-
-        with open(file=local_file, mode="rb") as fp:
-            encoder = MultipartEncoder(fields={"filename": os.path.basename(remote_file), "file": ("filename", fp, "application/octet-stream")})
-            header = {"File-Path": remote_file, "Content-Type": encoder.content_type}
-
-            # Include file attributes (permissions, owner, group) if requested
-            if apply_file_attributes:
-                file_stat = os.stat(local_file)
-                header["File-Mode"] = str(file_stat.st_mode & 0o777)  # Mask to keep only permission bits
-                header["File-User"] = str(file_stat.st_uid)
-                header["File-Group"] = str(file_stat.st_gid)
-
-            # Upload file with or without attributes
-            # https://stackoverflow.com/questions/22567306/python-requests-file-upload
-            resp = self._request_http(
-                AppMeshClient.Method.POST_STREAM,
-                path="/appmesh/file/upload",
-                header=header,
-                body=encoder,
-            )
-            resp.raise_for_status()
-
-    ########################################
-    # Application run
-    ########################################
-    def _parse_duration(self, timeout) -> str:
-        if isinstance(timeout, int):
-            return str(timeout)
-        elif isinstance(timeout, str):
-            return str(int(aniso8601.parse_duration(timeout).total_seconds()))
-        else:
-            raise TypeError(f"Invalid timeout type: {str(timeout)}")
-
-    def run_async(
-        self,
-        app: Union[App, str],
-        max_time_seconds: Union[int, str] = DURATION_TWO_DAYS_ISO,
-        life_cycle_seconds: Union[int, str] = DURATION_TWO_DAYS_HALF_ISO,
-    ) -> AppRun:
-        """Run an application asynchronously on a remote system without blocking the API.
-
-        Args:
-            app (Union[App, str]): An `App` instance or a shell command string.
-                - If `app` is a string, it is treated as a shell command for the remote run,
-                and an `App` instance is created as:
-                `App({"command": "<command_string>", "shell": True})`.
-                - If `app` is an `App` object, providing only the `name` attribute (without
-                a command) will run an existing application; otherwise, it is treated as a new application.
-            max_time_seconds (Union[int, str], optional): Maximum runtime for the remote process.
-                Accepts ISO 8601 duration format (e.g., 'P1Y2M3DT4H5M6S', 'P5W'). Defaults to `P2D`.
-            life_cycle_seconds (Union[int, str], optional): Maximum lifecycle time for the remote process.
-                Accepts ISO 8601 duration format. Defaults to `P2DT12H`.
-
-        Returns:
-            AppRun: An application run object that can be used to monitor and retrieve the result of the run.
-        """
-        if isinstance(app, str):
-            app = App({"command": app, "shell": True})
-
-        path = "/appmesh/app/run"
-        resp = self._request_http(
-            AppMeshClient.Method.POST,
-            body=app.json(),
-            path=path,
-            query={
-                "timeout": self._parse_duration(max_time_seconds),
-                "lifecycle": self._parse_duration(life_cycle_seconds),
-            },
-        )
-        if resp.status_code != HTTPStatus.OK:
-            raise Exception(resp.text)
-
-        # Return an AppRun object with the application name and process UUID
-        return AppRun(self, resp.json()["name"], resp.json()["process_uuid"])
-
-    def run_async_wait(self, run: AppRun, stdout_print: bool = True, timeout: int = 0) -> int:
-        """Wait for an async run to be finished
-
-        Args:
-            run (AppRun): asyncrized run result from run_async().
-            stdout_print (bool, optional): print remote stdout to local or not.
-            timeout (int, optional): wait max timeout seconds and return if not finished, 0 means wait until finished
-
-        Returns:
-            int: return exit code if process finished, return None for timeout or exception.
-        """
-        if run:
-            last_output_position = 0
-            start = datetime.now()
-            interval = 1 if self.__class__.__name__ == "AppMeshClient" else 1000
-            while len(run.proc_uid) > 0:
-                app_out = self.app_output(app_name=run.app_name, stdout_position=last_output_position, stdout_index=0, process_uuid=run.proc_uid, timeout=interval)
-                if app_out.output and stdout_print:
-                    print(app_out.output, end="")
-                if app_out.out_position is not None:
-                    last_output_position = app_out.out_position
-                if app_out.exit_code is not None:
-                    # success
-                    self.app_delete(run.app_name)
-                    return app_out.exit_code
-                if app_out.status_code != HTTPStatus.OK:
-                    # failed
-                    break
-                if timeout > 0 and (datetime.now() - start).seconds > timeout:
-                    # timeout
-                    break
-        return None
-
-    def run_sync(
-        self,
-        app: Union[App, str],
-        stdout_print: bool = True,
-        max_time_seconds: Union[int, str] = DURATION_TWO_DAYS_ISO,
-        life_cycle_seconds: Union[int, str] = DURATION_TWO_DAYS_HALF_ISO,
-    ) -> Tuple[Union[int, None], str]:
-        """Synchronously run an application remotely, blocking until completion, and return the result.
-
-        If 'app' is a string, it is treated as a shell command and converted to an App instance.
-        If 'app' is App object, the name attribute is used to run an existing application if specified.
-
-        Args:
-            app (Union[App, str]): An App instance or a shell command string.
-                If a string, an App instance is created as:
-                `appmesh_client.App({"command": "<command_string>", "shell": True})`
-            stdout_print (bool, optional): If True, prints the remote stdout locally. Defaults to True.
-            max_time_seconds (Union[int, str], optional): Maximum runtime for the remote process.
-                Supports ISO 8601 duration format (e.g., 'P1Y2M3DT4H5M6S', 'P5W'). Defaults to DEFAULT_RUN_APP_TIMEOUT_SECONDS.
-            life_cycle_seconds (Union[int, str], optional): Maximum lifecycle time for the remote process.
-                Supports ISO 8601 duration format. Defaults to DEFAULT_RUN_APP_LIFECYCLE_SECONDS.
-
-        Returns:
-            Tuple[Union[int, None], str]: Exit code of the process (None if unavailable) and the stdout text.
-        """
-        if isinstance(app, str):
-            app = App({"command": app, "shell": True})
-
-        path = "/appmesh/app/syncrun"
-        resp = self._request_http(
-            AppMeshClient.Method.POST,
-            body=app.json(),
-            path=path,
-            query={
-                "timeout": self._parse_duration(max_time_seconds),
-                "lifecycle": self._parse_duration(life_cycle_seconds),
-            },
-        )
-        exit_code = None
-        if resp.status_code == HTTPStatus.OK:
-            if stdout_print:
-                print(resp.text, end="")
-            if "Exit-Code" in resp.headers:
-                exit_code = int(resp.headers.get("Exit-Code"))
-        elif stdout_print:
-            print(resp.text)
-
-        return exit_code, resp.text
-
-    def _request_http(self, method: Method, path: str, query: dict = None, header: dict = None, body=None) -> requests.Response:
-        """REST API
-
-        Args:
-            method (Method): AppMeshClient.Method.
-            path (str): URI patch str.
-            query (dict, optional): HTTP query parameters.
-            header (dict, optional): HTTP headers.
-            body (_type_, optional): object to send in the body of the :class:`Request`.
-
-        Returns:
-            requests.Response: HTTP response
-        """
-        rest_url = parse.urljoin(self.server_url, path)
-
-        header = {} if header is None else header
-        if self.jwt_token:
-            header["Authorization"] = "Bearer " + self.jwt_token
-        if self.forwarding_host and len(self.forwarding_host) > 0:
-            if ":" in self.forwarding_host:
-                header[self.HTTP_HEADER_KEY_X_TARGET_HOST] = self.forwarding_host
-            else:
-                header[self.HTTP_HEADER_KEY_X_TARGET_HOST] = self.forwarding_host + ":" + str(parse.urlsplit(self.server_url).port)
-        header[self.HTTP_HEADER_KEY_USER_AGENT] = self.HTTP_USER_AGENT
-
-        if method is AppMeshClient.Method.GET:
-            return requests.get(url=rest_url, params=query, headers=header, cert=self.ssl_client_cert, verify=self.ssl_verify, timeout=self.rest_timeout)
-        elif method is AppMeshClient.Method.POST:
-            return requests.post(
-                url=rest_url, params=query, headers=header, data=json.dumps(body) if type(body) in (dict, list) else body, cert=self.ssl_client_cert, verify=self.ssl_verify, timeout=self.rest_timeout
-            )
-        elif method is AppMeshClient.Method.POST_STREAM:
-            return requests.post(url=rest_url, params=query, headers=header, data=body, cert=self.ssl_client_cert, verify=self.ssl_verify, stream=True, timeout=self.rest_timeout)
-        elif method is AppMeshClient.Method.DELETE:
-            return requests.delete(url=rest_url, headers=header, cert=self.ssl_client_cert, verify=self.ssl_verify, timeout=self.rest_timeout)
-        elif method is AppMeshClient.Method.PUT:
-            return requests.put(url=rest_url, params=query, headers=header, json=body, cert=self.ssl_client_cert, verify=self.ssl_verify, timeout=self.rest_timeout)
-        else:
-            raise Exception("Invalid http method", method)
+from .http_client import AppMeshClient, App, AppOutput