embed-client-dev 4.0.78__py3-none-any.whl

embed_client/config.py

@@ -0,0 +1,408 @@
+"""
+Client configuration management module.
+
+This module provides configuration management for the embed-client,
+supporting all security modes and authentication methods.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import json
+import os
+from copy import deepcopy
+from typing import Any, Dict, List, Optional
+
+from embed_client.config_defaults import DEFAULT_CONFIG, update_nested_dict
+from embed_client.config_presets import (
+    create_http_config_for_class,
+    create_http_token_config_for_class,
+    create_https_config_for_class,
+    create_https_token_config_for_class,
+    create_mtls_config_for_class,
+    create_minimal_config_dict,
+    create_secure_config_dict,
+    load_env_variables,
+    validate_client_config,
+)
+
+
+class ClientConfig:
+    """
+    Configuration management class for the embed-client.
+    Allows loading settings from configuration file and environment variables.
+    Supports all security modes and authentication methods.
+    """
+
+    def __init__(self, config_path: Optional[str] = None):
+        """
+        Initialize client configuration.
+
+        Args:
+            config_path: Path to configuration file. If not specified,
+                        "./config.json" is used.
+        """
+        self.config_path = config_path or "./config.json"
+        self.config_data: Dict[str, Any] = {}
+        self.load_config()
+
+    def load_config(self) -> None:
+        """
+        Load configuration from file and environment variables.
+        """
+        # Set default config values (deep copy to avoid global mutation)
+        self.config_data = deepcopy(DEFAULT_CONFIG)
+
+        # Try to load configuration from file
+        if os.path.exists(self.config_path):
+            try:
+                with open(self.config_path, "r", encoding="utf-8") as f:
+                    file_config = json.load(f)
+                    # The default ``server.base_url`` must not override an
+                    # explicitly configured host/port (adapter prefers base_url).
+                    file_server = file_config.get("server")
+                    if (
+                        isinstance(file_server, dict)
+                        and ("host" in file_server or "port" in file_server)
+                        and "base_url" not in file_server
+                    ):
+                        self.config_data["server"].pop("base_url", None)
+                    update_nested_dict(self.config_data, file_config)
+            except Exception as e:
+                print(f"Error loading config from {self.config_path}: {e}")
+
+        # Load configuration from environment variables
+        load_env_variables(self.config_data)
+
+    def load_from_file(self, config_path: str) -> None:
+        """
+        Load configuration from the specified file.
+
+        Args:
+            config_path: Path to configuration file.
+        """
+        self.config_path = config_path
+        self.load_config()
+
+    def load_config_file(self, config_path: str) -> None:
+        """Backward-compatible alias for :meth:`load_from_file`."""
+        self.load_from_file(config_path)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get configuration value for key.
+
+        Args:
+            key: Configuration key in format "section.param"
+            default: Default value if key not found
+
+        Returns:
+            Configuration value
+        """
+        parts = key.split(".")
+
+        # Get value from config
+        value = self.config_data
+        for part in parts:
+            if not isinstance(value, dict) or part not in value:
+                return default
+            value = value[part]
+
+        return value
+
+    def get_all(self) -> Dict[str, Any]:
+        """
+        Get all configuration values.
+
+        Returns:
+            Dictionary with all configuration values
+        """
+        return self.config_data.copy()
+
+    def set(self, key: str, value: Any) -> None:
+        """
+        Set configuration value for key.
+
+        Args:
+            key: Configuration key in format "section.param"
+            value: Configuration value
+        """
+        parts = key.split(".")
+        if len(parts) == 1:
+            self.config_data[key] = value
+        else:
+            section = parts[0]
+
+            if section not in self.config_data:
+                self.config_data[section] = {}
+
+            current = self.config_data[section]
+            for part in parts[1:-1]:
+                if part not in current:
+                    current[part] = {}
+                current = current[part]
+
+            current[parts[-1]] = value
+
+    def save(self, path: Optional[str] = None) -> None:
+        """
+        Save configuration to file.
+
+        Args:
+            path: Path to configuration file. If not specified,
+                  self.config_path is used.
+        """
+        save_path = path or self.config_path
+        with open(save_path, "w", encoding="utf-8") as f:
+            json.dump(self.config_data, f, indent=2)
+
+    def configure_auth_mode(self, mode: str, **kwargs) -> None:
+        """
+        Configure authentication mode.
+
+        Args:
+            mode: Authentication mode (none, api_key, jwt, certificate, basic)
+            **kwargs: Additional configuration parameters
+        """
+        self.set("auth.method", mode)
+
+        if mode == "api_key":
+            if "key" in kwargs:
+                self.set("auth.api_key.key", kwargs["key"])
+            if "header" in kwargs:
+                self.set("auth.api_key.header", kwargs["header"])
+        elif mode == "jwt":
+            if "username" in kwargs:
+                self.set("auth.jwt.username", kwargs["username"])
+            if "password" in kwargs:
+                self.set("auth.jwt.password", kwargs["password"])
+            if "secret" in kwargs:
+                self.set("auth.jwt.secret", kwargs["secret"])
+            if "expiry_hours" in kwargs:
+                self.set("auth.jwt.expiry_hours", kwargs["expiry_hours"])
+        elif mode == "certificate":
+            self.set("auth.certificate.enabled", True)
+            if "cert_file" in kwargs:
+                self.set("auth.certificate.cert_file", kwargs["cert_file"])
+            if "key_file" in kwargs:
+                self.set("auth.certificate.key_file", kwargs["key_file"])
+            if "ca_cert_file" in kwargs:
+                self.set("auth.certificate.ca_cert_file", kwargs["ca_cert_file"])
+        elif mode == "basic":
+            if "username" in kwargs:
+                self.set("auth.basic.username", kwargs["username"])
+            if "password" in kwargs:
+                self.set("auth.basic.password", kwargs["password"])
+
+    def configure_ssl(self, enabled: bool = True, **kwargs) -> None:
+        """
+        Configure SSL/TLS settings.
+
+        Args:
+            enabled: Enable SSL/TLS
+            **kwargs: Additional SSL configuration parameters
+        """
+        self.set("ssl.enabled", enabled)
+
+        if "verify" in kwargs:
+            self.set("ssl.verify", kwargs["verify"])
+        if "check_hostname" in kwargs:
+            self.set("ssl.check_hostname", kwargs["check_hostname"])
+        if "cert_file" in kwargs:
+            self.set("ssl.cert_file", kwargs["cert_file"])
+        if "key_file" in kwargs:
+            self.set("ssl.key_file", kwargs["key_file"])
+        if "ca_cert_file" in kwargs:
+            self.set("ssl.ca_cert_file", kwargs["ca_cert_file"])
+        if "client_cert_required" in kwargs:
+            self.set("ssl.client_cert_required", kwargs["client_cert_required"])
+
+    def configure_server(
+        self, host: str, port: int, base_url: Optional[str] = None
+    ) -> None:
+        """
+        Configure server connection settings.
+
+        Args:
+            host: Server host
+            port: Server port
+            base_url: Full server URL (optional, will be constructed if not provided)
+        """
+        self.set("server.host", host)
+        self.set("server.port", port)
+
+        if base_url:
+            self.set("server.base_url", base_url)
+        else:
+            protocol = "https" if self.get("ssl.enabled", False) else "http"
+            self.set("server.base_url", f"{protocol}://{host}:{port}")
+
+    def get_server_url(self) -> str:
+        """
+        Get the complete server URL.
+
+        Returns:
+            Server URL string
+        """
+        return self.get("server.base_url", "http://localhost:8001")
+
+    def get_auth_method(self) -> str:
+        """
+        Get the authentication method.
+
+        Returns:
+            Authentication method string
+        """
+        return self.get("auth.method", "none")
+
+    def is_ssl_enabled(self) -> bool:
+        """
+        Check if SSL/TLS is enabled.
+
+        Returns:
+            True if SSL is enabled, False otherwise
+        """
+        return self.get("ssl.enabled", False)
+
+    def is_auth_enabled(self) -> bool:
+        """
+        Check if authentication is enabled.
+
+        Returns:
+            True if authentication is enabled, False otherwise
+        """
+        return self.get("auth.method", "none") != "none"
+
+    def is_security_enabled(self) -> bool:
+        """
+        Check if security features are enabled.
+
+        Returns:
+            True if security is enabled, False otherwise
+        """
+        return self.get("security.enabled", False)
+
+    def validate_config(self) -> List[str]:
+        """Validate configuration and return list of validation error messages."""
+        return validate_client_config(self)
+
+    def create_minimal_config(self) -> Dict[str, Any]:
+        """Create minimal configuration with only essential features."""
+        return create_minimal_config_dict(self)
+
+    def create_secure_config(self) -> Dict[str, Any]:
+        """Create secure configuration with all security features enabled."""
+        return create_secure_config_dict(self)
+
+    @classmethod
+    def from_dict(cls, config_dict: Dict[str, Any]) -> "ClientConfig":
+        """
+        Create ClientConfig instance from dictionary.
+
+        Args:
+            config_dict: Configuration dictionary
+
+        Returns:
+            ClientConfig instance
+        """
+        config = cls()
+        config.config_data = update_nested_dict(config.config_data, config_dict)
+        return config
+
+    @classmethod
+    def from_file(cls, config_path: str) -> "ClientConfig":
+        """
+        Create ClientConfig instance from file.
+
+        Args:
+            config_path: Path to configuration file
+
+        Returns:
+            ClientConfig instance
+        """
+        config = cls(config_path)
+        return config
+
+    @classmethod
+    def create_http_config(
+        cls, host: str = "localhost", port: int = 8001
+    ) -> "ClientConfig":
+        """Create configuration for HTTP connection without authentication."""
+        return create_http_config_for_class(cls, host=host, port=port)
+
+    @classmethod
+    def create_http_token_config(
+        cls,
+        host: str = "localhost",
+        port: int = 8001,
+        api_key: Optional[str] = None,
+    ) -> "ClientConfig":
+        """Create configuration for HTTP connection with API key authentication."""
+        return create_http_token_config_for_class(
+            cls,
+            host=host,
+            port=port,
+            api_key=api_key,
+        )
+
+    @classmethod
+    def create_https_config(
+        cls,
+        host: str = "localhost",
+        port: int = 8443,
+        cert_file: Optional[str] = None,
+        key_file: Optional[str] = None,
+        ca_cert_file: Optional[str] = None,
+    ) -> "ClientConfig":
+        """Create configuration for HTTPS connection without authentication."""
+        return create_https_config_for_class(
+            cls,
+            host=host,
+            port=port,
+            cert_file=cert_file,
+            key_file=key_file,
+            ca_cert_file=ca_cert_file,
+        )
+
+    @classmethod
+    def create_https_token_config(
+        cls,
+        host: str = "localhost",
+        port: int = 8443,
+        api_key: Optional[str] = None,
+        cert_file: Optional[str] = None,
+        key_file: Optional[str] = None,
+        ca_cert_file: Optional[str] = None,
+    ) -> "ClientConfig":
+        """Create configuration for HTTPS connection with API key authentication."""
+        return create_https_token_config_for_class(
+            cls,
+            host=host,
+            port=port,
+            api_key=api_key,
+            cert_file=cert_file,
+            key_file=key_file,
+            ca_cert_file=ca_cert_file,
+        )
+
+    @classmethod
+    def create_mtls_config(
+        cls,
+        host: str = "localhost",
+        port: int = 8443,
+        cert_file: Optional[str] = None,
+        key_file: Optional[str] = None,
+        ca_cert_file: Optional[str] = None,
+    ) -> "ClientConfig":
+        """Create configuration for mTLS connection with client certificates."""
+        return create_mtls_config_for_class(
+            cls,
+            host=host,
+            port=port,
+            cert_file=cert_file,
+            key_file=key_file,
+            ca_cert_file=ca_cert_file,
+        )
+
+
+# Singleton instance

embed_client/config_defaults.py

@@ -0,0 +1,77 @@
+"""
+Default configuration and helpers for embed-client ClientConfig.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+DEFAULT_CONFIG: Dict[str, Any] = {
+    "server": {
+        "host": "localhost",
+        "port": 8001,
+        "base_url": "http://localhost:8001",
+    },
+    "timeout": 30,
+    "retry_attempts": 3,
+    "retry_delay": 1,
+    "auth": {
+        "method": "none",  # none, api_key, jwt, certificate, basic
+        "api_key": {"key": None, "header": "X-API-Key"},
+        "jwt": {
+            "username": None,
+            "password": None,
+            "secret": None,
+            "expiry_hours": 24,
+        },
+        "certificate": {
+            "enabled": False,
+            "cert_file": None,
+            "key_file": None,
+            "ca_cert_file": None,
+        },
+        "basic": {"username": None, "password": None},
+    },
+    "ssl": {
+        "enabled": False,
+        "verify": True,
+        "check_hostname": True,
+        "cert_file": None,
+        "key_file": None,
+        "ca_cert_file": None,
+        "client_cert_required": False,
+    },
+    "security": {"enabled": False, "roles_enabled": False, "roles_file": None},
+    "logging": {
+        "enabled": False,
+        "level": "INFO",
+        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    },
+    "client": {"timeout": 30.0},
+}
+
+
+def update_nested_dict(
+    target: Dict[str, Any], updates: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Recursively update a nested dictionary in place.
+
+    Args:
+        target: Dictionary to update.
+        updates: Dictionary with new values.
+
+    Returns:
+        The updated dictionary (same instance as ``target``).
+    """
+    for key, value in updates.items():
+        if isinstance(value, dict) and key in target and isinstance(target[key], dict):
+            update_nested_dict(target[key], value)
+        else:
+            target[key] = value
+    return target
+
+
+__all__ = ["DEFAULT_CONFIG", "update_nested_dict"]

embed_client/config_examples.py

@@ -0,0 +1,228 @@
+"""
+Configuration examples for all security modes.
+
+This module provides ready-to-use configuration examples for all supported
+security modes and authentication methods.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from typing import Dict, Any, Optional
+from embed_client.config import ClientConfig
+
+
+def get_http_simple_config(host: str = "localhost", port: int = 8001) -> Dict[str, Any]:
+    """
+    Get configuration for HTTP connection without authentication.
+
+    Args:
+        host: Server host
+        port: Server port
+
+    Returns:
+        Configuration dictionary
+    """
+    config = ClientConfig.create_http_config(host, port)
+    return config.get_all()
+
+
+def get_http_token_config(
+    host: str = "localhost", port: int = 8001, api_key: str = "test-token-123"
+) -> Dict[str, Any]:
+    """
+    Get configuration for HTTP connection with API key authentication.
+
+    Args:
+        host: Server host
+        port: Server port
+        api_key: API key for authentication
+
+    Returns:
+        Configuration dictionary
+    """
+    config = ClientConfig.create_http_token_config(host, port, api_key)
+    return config.get_all()
+
+
+def get_https_simple_config(
+    host: str = "localhost",
+    port: int = 8443,
+    cert_file: Optional[str] = None,
+    key_file: Optional[str] = None,
+    ca_cert_file: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Get configuration for HTTPS connection without authentication.
+
+    Args:
+        host: Server host
+        port: Server port
+        cert_file: Client certificate file (optional)
+        key_file: Client key file (optional)
+        ca_cert_file: CA certificate file (optional)
+
+    Returns:
+        Configuration dictionary
+    """
+    config = ClientConfig.create_https_config(
+        host, port, cert_file, key_file, ca_cert_file
+    )
+    return config.get_all()
+
+
+def get_https_token_config(
+    host: str = "localhost",
+    port: int = 8443,
+    api_key: str = "test-token-123",
+    cert_file: Optional[str] = None,
+    key_file: Optional[str] = None,
+    ca_cert_file: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Get configuration for HTTPS connection with API key authentication.
+
+    Args:
+        host: Server host
+        port: Server port
+        api_key: API key for authentication
+        cert_file: Client certificate file (optional)
+        key_file: Client key file (optional)
+        ca_cert_file: CA certificate file (optional)
+
+    Returns:
+        Configuration dictionary
+    """
+    config = ClientConfig.create_https_token_config(
+        host, port, api_key, cert_file, key_file, ca_cert_file
+    )
+    return config.get_all()
+
+
+def get_mtls_config(
+    host: str = "localhost",
+    port: int = 8443,
+    cert_file: str = "certs/client.crt",
+    key_file: str = "keys/client.key",
+    ca_cert_file: str = "certs/ca.crt",
+) -> Dict[str, Any]:
+    """
+    Get configuration for mTLS connection with client certificates.
+
+    Args:
+        host: Server host
+        port: Server port
+        cert_file: Client certificate file
+        key_file: Client key file
+        ca_cert_file: CA certificate file
+
+    Returns:
+        Configuration dictionary
+    """
+    config = ClientConfig.create_mtls_config(
+        host, port, cert_file, key_file, ca_cert_file
+    )
+    return config.get_all()
+
+
+def get_jwt_config(
+    host: str = "localhost",
+    port: int = 8001,
+    username: str = "user",
+    password: str = "password",
+    secret: str = "jwt-secret",
+    expiry_hours: int = 24,
+) -> Dict[str, Any]:
+    """
+    Get configuration for HTTP connection with JWT authentication.
+
+    Args:
+        host: Server host
+        port: Server port
+        username: Username for JWT
+        password: Password for JWT
+        secret: JWT secret key
+        expiry_hours: JWT token expiry in hours
+
+    Returns:
+        Configuration dictionary
+    """
+    config = ClientConfig()
+    config.configure_server(host, port)
+    config.configure_auth_mode(
+        "jwt",
+        username=username,
+        password=password,
+        secret=secret,
+        expiry_hours=expiry_hours,
+    )
+    return config.get_all()
+
+
+def get_basic_auth_config(
+    host: str = "localhost",
+    port: int = 8001,
+    username: str = "user",
+    password: str = "password",
+) -> Dict[str, Any]:
+    """
+    Get configuration for HTTP connection with basic authentication.
+
+    Args:
+        host: Server host
+        port: Server port
+        username: Username for basic auth
+        password: Password for basic auth
+
+    Returns:
+        Configuration dictionary
+    """
+    config = ClientConfig()
+    config.configure_server(host, port)
+    config.configure_auth_mode("basic", username=username, password=password)
+    return config.get_all()
+
+
+def get_all_config_examples() -> Dict[str, Dict[str, Any]]:
+    """
+    Get all configuration examples.
+
+    Returns:
+        Dictionary with all configuration examples
+    """
+    return {
+        "http_simple": get_http_simple_config(),
+        "http_token": get_http_token_config(),
+        "https_simple": get_https_simple_config(),
+        "https_token": get_https_token_config(),
+        "mtls": get_mtls_config(),
+        "jwt": get_jwt_config(),
+        "basic_auth": get_basic_auth_config(),
+    }
+
+
+def save_config_examples(output_dir: str = "configs") -> None:
+    """
+    Save all configuration examples to files.
+
+    Args:
+        output_dir: Output directory for configuration files
+    """
+    import os
+    import json
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    examples = get_all_config_examples()
+
+    for name, config in examples.items():
+        filename = os.path.join(output_dir, f"{name}.json")
+        with open(filename, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2, ensure_ascii=False)
+        print(f"Saved configuration: {filename}")
+
+
+if __name__ == "__main__":
+    # Save all configuration examples
+    save_config_examples()
+    print("All configuration examples saved to 'configs/' directory")