blackant-sdk 1.0.2__py3-none-any.whl

blackant/exceptions.py

@@ -0,0 +1,111 @@
+"""BlackAnt SDK exception classes.
+
+Central exception hierarchy for all BlackAnt SDK errors.
+"""
+
+
+class BlackAntException(Exception):
+    """Base exception for all BlackAnt SDK errors.
+
+    All SDK-specific exceptions inherit from this base class
+    to allow catching all SDK errors with a single handler.
+    """
+
+
+class BlackAntAuthenticationError(BlackAntException):
+    """Authentication and authorization related errors.
+
+    Raised when:
+    - Login credentials are invalid
+    - Keycloak authentication fails
+    - Bearer token is missing or expired
+    - Authorization is denied
+    """
+
+
+class BlackAntDockerError(BlackAntException):
+    """Docker operation related errors.
+
+    Raised when:
+    - Docker API calls fail
+    - Container operations encounter issues
+    - Image operations fail
+    - Registry communication errors
+    """
+
+
+class BlackAntConnectionError(BlackAntException):
+    """Network and connection related errors.
+
+    Raised when:
+    - HTTP requests timeout
+    - Network connection fails
+    - API endpoints are unreachable
+    """
+
+
+class BlackAntConfigurationError(BlackAntException):
+    """Configuration related errors.
+
+    Raised when:
+    - Required environment variables are missing
+    - Configuration files are invalid
+    - Service configuration is incorrect
+    """
+
+
+# =============================================================================
+# Keycloak & Role Assignment Exceptions
+# =============================================================================
+
+
+class KeycloakError(BlackAntException):
+    """Base exception for Keycloak-related errors.
+
+    All Keycloak-specific exceptions inherit from this base class
+    to allow catching all Keycloak errors with a single handler.
+    """
+
+
+class KeycloakConnectionError(KeycloakError):
+    """Raised when connection to Keycloak server fails.
+
+    This can occur due to:
+    - Network connectivity issues
+    - Incorrect server URL
+    - Firewall blocking connection
+    - Keycloak server being down
+    """
+
+
+class KeycloakAuthenticationError(KeycloakError):
+    """Raised when Keycloak authentication fails.
+
+    This can occur due to:
+    - Invalid service account credentials
+    - Expired client secret
+    - Incorrect client ID
+    - Insufficient permissions for service account
+    """
+
+
+class RoleAssignmentError(KeycloakError):
+    """Raised when role assignment operation fails.
+
+    This can occur due to:
+    - Role does not exist in realm
+    - User does not exist
+    - Insufficient permissions to assign role
+    - Keycloak API error during assignment
+    """
+
+
+class TokenValidationError(BlackAntException):
+    """Raised when JWT token validation fails.
+
+    This can occur due to:
+    - Invalid token format
+    - Missing required claims (sub, etc.)
+    - Expired token
+    - Token signature validation failure
+    """

blackant/http/__init__.py

@@ -0,0 +1,8 @@
+"""BlackAnt SDK HTTP module.
+
+Provides HTTP client functionality for BlackAnt SDK API communication.
+"""
+
+from .client import HTTPClient, HTTPConnectionError
+
+__all__ = ["HTTPClient", "HTTPConnectionError"]

blackant/http/client.py

@@ -0,0 +1,125 @@
+"""BlackAnt SDK HTTP communication module.
+
+HTTP client with Bearer token authentication, request ID tracking,
+and integration with auth store modules.
+"""
+
+import requests
+from requests.adapters import HTTPAdapter
+
+from ..auth.tokens import AuthTokenStore
+from ..auth.request_id import RequestIdStore
+from ..utils.logging import get_logger, set_request_id, clear_request_id
+
+
+class HTTPConnectionError(Exception):
+    """HTTP connection specific exception.
+
+    Raised when HTTP requests fail due to connection issues,
+    timeouts, or network problems.
+    """
+
+
+class HTTPClient:  # pylint: disable=too-few-public-methods
+    """HTTP client for BlackAnt SDK API communication.
+
+    Provides HTTP request functionality with automatic Bearer token injection,
+    request ID tracking, and base URL management.
+
+    Args:
+        base_url (str): Base URL for API endpoints.
+        auth_token_store (AuthTokenStore, optional): Token storage instance.
+        request_id_store (RequestIdStore, optional): Request ID storage instance.
+
+    Examples:
+        >>> client = HTTPClient("https://api.blackant.app")
+        >>> client.auth_token_store.user_token = "your_token"
+        >>> response = client.send_request("/api/v1/services", "GET")
+    """
+
+    def __init__(self, base_url, auth_token_store=None, request_id_store=None):
+        """Initialize HTTP client.
+
+        Args:
+            base_url (str): Base URL for API endpoints.
+            auth_token_store (AuthTokenStore, optional): Token storage.
+            request_id_store (RequestIdStore, optional): Request ID storage.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.auth_token_store = auth_token_store or AuthTokenStore()
+        self.request_id_store = request_id_store or RequestIdStore()
+        self.logger = get_logger("http")
+
+        self.session = requests.Session()
+        adapter = HTTPAdapter(pool_connections=10, pool_maxsize=20, max_retries=0)
+        self.session.mount("https://", adapter)
+        self.session.mount("http://", adapter)
+
+    def send_request(  # pylint: disable=too-many-arguments
+        self,
+        endpoint,
+        method,
+        json=None,
+        anonymous=False,
+        is_admin=False,
+        req_timeout=60.0,
+        token=None,
+    ):
+        """Send HTTP request to the configured API endpoint.
+
+        Args:
+            endpoint (str): API endpoint path.
+            method (str): HTTP method.
+            json (dict, optional): JSON data for request body.
+            anonymous (bool): Skip Bearer token authentication.
+            is_admin (bool): Use admin token instead of user token.
+            req_timeout (float): Request timeout in seconds.
+            token (str, optional): Custom Bearer token.
+
+        Returns:
+            requests.Response: HTTP response object.
+
+        Raises:
+            HTTPConnectionError: When connection fails or times out.
+        """
+        request_id = self.request_id_store.generate_id()
+        set_request_id(request_id)
+
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+
+        try:
+            req = requests.Request(method, url, json=json)
+            prepped = self.session.prepare_request(req)
+
+            if not anonymous:
+                if token:
+                    prepped.headers["Authorization"] = f"Bearer {token}"
+                else:
+                    auth_token = (
+                        self.auth_token_store.admin_token if is_admin
+                        else self.auth_token_store.user_token
+                    )
+                    if auth_token:
+                        prepped.headers["Authorization"] = f"Bearer {auth_token}"
+
+            prepped.headers[self.request_id_store.header_name] = request_id
+
+            # Determine if we should verify SSL (skip for localhost/dev)
+            verify_ssl = not (
+                "localhost" in self.base_url or
+                "127.0.0.1" in self.base_url or
+                "http://" in url or  # HTTP doesn't need SSL verification
+                "dev.blackant.app" in self.base_url  # Dev environment self-signed cert
+            )
+
+            response = self.session.send(prepped, timeout=req_timeout, verify=verify_ssl)
+            return response
+
+        except requests.exceptions.ConnectionError as exc:
+            self.logger.error(f"Connection error: {exc}")
+            raise HTTPConnectionError from exc
+        except requests.exceptions.Timeout as exc:
+            self.logger.error(f"Request time-out error: {exc}")
+            raise HTTPConnectionError from exc
+        finally:
+            clear_request_id()

blackant/patterns/__init__.py

@@ -0,0 +1 @@
+"""Pattern implementations for BlackAnt SDK."""

blackant/patterns/singleton.py

@@ -0,0 +1,20 @@
+"""Singleton pattern implementation for BlackAnt SDK."""
+
+import threading
+
+
+class Singleton(type):
+    """Singleton metaclass implementation.
+
+    Thread-safe singleton pattern using metaclass approach.
+    Ensures only one instance per class exists across the application.
+    """
+    _instances = {}
+    _lock = threading.Lock()
+
+    def __call__(cls, *args, **kwargs):
+        if cls not in cls._instances:
+            with cls._lock:
+                if cls not in cls._instances:
+                    cls._instances[cls] = super(Singleton, cls).__call__(*args, **kwargs)
+        return cls._instances[cls]

blackant/services/__init__.py

@@ -0,0 +1,10 @@
+"""BlackAnt Services module.
+
+Service registry and lifecycle management components with both
+HTTP API (external) and Docker SDK (internal) support.
+"""
+
+from .registry import ServiceRegistry
+from .dao import ServiceManagerDAO
+
+__all__ = ["ServiceRegistry", "ServiceManagerDAO"]

blackant/services/dao.py

@@ -0,0 +1,414 @@
+"""ServiceManager DAO - Docker SDK objektum szintű service kezelés.
+
+High-level Docker service operations using Docker SDK objects directly,
+following the BlackAnt "Docker as Object" design pattern.
+"""
+
+import logging
+import time
+import random
+from typing import Optional, List, Dict, Any, Union
+from dataclasses import dataclass, field
+
+import docker
+from docker.models.services import Service as DockerServiceObject
+from docker.models.containers import Container as DockerContainer
+from docker.errors import DockerException, NotFound, APIError
+
+from ..utils.logging import get_logger
+from ..exceptions import BlackAntDockerError
+
+
+@dataclass
+class ServiceConfig:
+    """Service configuration data class for ServiceManagerDAO."""
+
+    name: str = field(default="")
+    image: str = field(default="")
+    command: Optional[List[str]] = field(default=None)
+    environments: Dict[str, str] = field(default_factory=dict)
+    networks: List[str] = field(default_factory=list)
+    labels: Dict[str, str] = field(default_factory=dict)
+    constraints: List[str] = field(default_factory=list)
+    replicas: int = field(default=1)
+    cpu_limit: Optional[int] = field(default=None)  # nanocpus
+    memory_limit: Optional[int] = field(default=None)  # bytes
+    ports: Dict[str, int] = field(default_factory=dict)
+    mounts: List[Dict[str, str]] = field(default_factory=list)
+
+
+class ServiceManagerDAO:
+    """Docker Services objektum szintű kezelése.
+
+    Provides high-level service management operations using Docker SDK
+    objects directly instead of HTTP requests. This follows the BlackAnt
+    "Docker as Object" pattern for internal server-side operations.
+
+    Examples:
+        >>> dao = ServiceManagerDAO()
+        >>> config = ServiceConfig(name="my-service", image="nginx:latest")
+        >>> service = dao.create_service(config)
+        >>> services = dao.list_services()
+        >>> dao.remove_service(service.id)
+    """
+
+    def __init__(self, docker_host: Optional[str] = None):
+        """ServiceManager DAO inicializálása Docker client-tel.
+
+        Args:
+            docker_host: Optional Docker daemon host URL
+
+        Raises:
+            BlackAntDockerError: Ha a Docker client inicializálás sikertelen
+        """
+        self.logger = get_logger("service-manager-dao")
+
+        try:
+            if docker_host:
+                self.__docker_client = docker.DockerClient(base_url=docker_host)
+            else:
+                self.__docker_client = docker.from_env()
+
+            # Test connection
+            self.__docker_client.ping()
+            self.logger.info("ServiceManagerDAO initialized successfully")
+
+        except DockerException as docker_error:
+            error_msg = f"Docker client initialization failed: {docker_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from docker_error
+
+    def create_service(self, service_config: Union[ServiceConfig, Dict[str, Any]]) -> DockerServiceObject:
+        """Szolgáltatás létrehozása Docker SDK-val.
+
+        Args:
+            service_config: ServiceConfig object or configuration dictionary
+
+        Returns:
+            DockerServiceObject: Létrehozott Docker service objektum
+
+        Raises:
+            BlackAntDockerError: Docker API hiba esetén
+        """
+        # Convert dict to ServiceConfig if needed
+        if isinstance(service_config, dict):
+            config = ServiceConfig(**service_config)
+        else:
+            config = service_config
+
+        try:
+            # Prepare service creation parameters
+            create_params = {
+                'name': config.name,
+                'image': config.image,
+                'env': [f"{k}={v}" for k, v in config.environments.items()],
+                'networks': config.networks,
+                'labels': config.labels,
+                'mode': docker.types.ServiceMode('replicated', config.replicas)
+            }
+
+            # Add command if specified
+            if config.command:
+                create_params['command'] = config.command
+
+            # Add resource constraints if specified
+            if config.cpu_limit or config.memory_limit:
+                resources = docker.types.Resources(
+                    cpu_limit=config.cpu_limit,
+                    mem_limit=config.memory_limit
+                )
+                create_params['resources'] = resources
+
+            # Add placement constraints
+            if config.constraints:
+                create_params['constraints'] = config.constraints
+
+            # Add port mappings if specified
+            if config.ports:
+                endpoint_spec = docker.types.EndpointSpec(
+                    ports={port: target for port, target in config.ports.items()}
+                )
+                create_params['endpoint_spec'] = endpoint_spec
+
+            # Add mounts if specified
+            if config.mounts:
+                mounts = []
+                for mount_config in config.mounts:
+                    mount = docker.types.Mount(
+                        target=mount_config['target'],
+                        source=mount_config['source'],
+                        type=mount_config.get('type', 'bind'),
+                        read_only=mount_config.get('read_only', False)
+                    )
+                    mounts.append(mount)
+                create_params['mounts'] = mounts
+
+            # Create service using Docker SDK
+            service = self.__docker_client.services.create(**create_params)
+
+            self.logger.info(f"Service created successfully: {service.name} (ID: {service.id})")
+            return service
+
+        except APIError as api_error:
+            error_msg = f"Service creation failed for '{config.name}': {api_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from api_error
+        except Exception as error:
+            error_msg = f"Unexpected error creating service '{config.name}': {error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from error
+
+    def get_service(self, service_id: str) -> Optional[DockerServiceObject]:
+        """Szolgáltatás lekérése ID vagy név alapján.
+
+        Args:
+            service_id: Service ID vagy név
+
+        Returns:
+            DockerServiceObject vagy None ha nem található
+
+        Raises:
+            BlackAntDockerError: Docker API hiba esetén (kivéve NotFound)
+        """
+        try:
+            service = self.__docker_client.services.get(service_id)
+            self.logger.debug(f"Service found: {service_id}")
+            return service
+
+        except NotFound:
+            self.logger.warning(f"Service not found: {service_id}")
+            return None
+
+        except APIError as api_error:
+            error_msg = f"Error getting service '{service_id}': {api_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from api_error
+
+    def list_services(self, filters: Optional[Dict[str, Any]] = None) -> List[DockerServiceObject]:
+        """Szolgáltatások listázása.
+
+        Args:
+            filters: Docker API szűrők (pl. {'label': 'env=prod'})
+
+        Returns:
+            List[DockerServiceObject]: Service objektumok listája
+
+        Raises:
+            BlackAntDockerError: Docker API hiba esetén
+        """
+        try:
+            services = self.__docker_client.services.list(filters=filters)
+            self.logger.debug(f"Found {len(services)} services")
+            return services
+
+        except APIError as api_error:
+            error_msg = f"Error listing services: {api_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from api_error
+
+    def remove_service(self, service_id: str) -> bool:
+        """Szolgáltatás eltávolítása.
+
+        Args:
+            service_id: Service ID vagy név
+
+        Returns:
+            bool: True ha sikeresen eltávolítva, False ha nem található
+
+        Raises:
+            BlackAntDockerError: Docker API hiba esetén (kivéve NotFound)
+        """
+        try:
+            service = self.get_service(service_id)
+            if service:
+                service.remove()
+                self.logger.info(f"Service removed successfully: {service_id}")
+                return True
+            else:
+                self.logger.warning(f"Service not found for removal: {service_id}")
+                return False
+
+        except APIError as api_error:
+            error_msg = f"Error removing service '{service_id}': {api_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from api_error
+
+    def update_service(self, service_id: str, **kwargs) -> Optional[DockerServiceObject]:
+        """Szolgáltatás frissítése.
+
+        Args:
+            service_id: Service ID vagy név
+            **kwargs: Frissítendő paraméterek (image, env, labels, stb.)
+
+        Returns:
+            DockerServiceObject vagy None ha nem található
+
+        Raises:
+            BlackAntDockerError: Docker API hiba esetén
+        """
+        try:
+            service = self.get_service(service_id)
+            if service:
+                # Refresh service object to get latest version
+                service.reload()
+
+                # Update service with provided parameters
+                service.update(**kwargs)
+
+                self.logger.info(f"Service updated successfully: {service_id}")
+                return service
+            else:
+                self.logger.warning(f"Service not found for update: {service_id}")
+                return None
+
+        except APIError as api_error:
+            error_msg = f"Error updating service '{service_id}': {api_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from api_error
+
+    def scale_service(self, service_id: str, replicas: int) -> Optional[DockerServiceObject]:
+        """Szolgáltatás méretezése (replicas számának változtatása).
+
+        Args:
+            service_id: Service ID vagy név
+            replicas: Új replicas szám
+
+        Returns:
+            DockerServiceObject vagy None ha nem található
+
+        Raises:
+            BlackAntDockerError: Docker API hiba esetén
+        """
+        try:
+            service = self.get_service(service_id)
+            if service:
+                # Scale service by updating replica count
+                mode = docker.types.ServiceMode('replicated', replicas)
+                service.update(mode=mode)
+
+                self.logger.info(f"Service scaled successfully: {service_id} -> {replicas} replicas")
+                return service
+            else:
+                self.logger.warning(f"Service not found for scaling: {service_id}")
+                return None
+
+        except APIError as api_error:
+            error_msg = f"Error scaling service '{service_id}': {api_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from api_error
+
+    def get_service_logs(self, service_id: str, **kwargs) -> str:
+        """Szolgáltatás naplóinak lekérése.
+
+        Args:
+            service_id: Service ID vagy név
+            **kwargs: Log opciók (tail, since, follow, stb.)
+
+        Returns:
+            str: Service logs
+
+        Raises:
+            BlackAntDockerError: Ha a service nem található vagy API hiba
+        """
+        try:
+            service = self.get_service(service_id)
+            if service:
+                logs = service.logs(**kwargs)
+                # Convert bytes to string if needed
+                if isinstance(logs, bytes):
+                    logs = logs.decode('utf-8')
+
+                self.logger.debug(f"Retrieved logs for service: {service_id}")
+                return logs
+            else:
+                raise BlackAntDockerError(f"Service not found: {service_id}")
+
+        except APIError as api_error:
+            error_msg = f"Error getting logs for service '{service_id}': {api_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from api_error
+
+    def is_service_running(self, service_id: str) -> bool:
+        """Ellenőrzi, hogy a szolgáltatásnak van-e futó task-ja.
+
+        Args:
+            service_id: Service ID vagy név
+
+        Returns:
+            bool: True ha van futó task, False egyébként
+        """
+        try:
+            service = self.get_service(service_id)
+            if service:
+                # Check if service has any running tasks
+                tasks = service.tasks()
+                for task in tasks:
+                    if task.get('Status', {}).get('State') == 'running':
+                        return True
+                return False
+            else:
+                return False
+
+        except Exception as error:
+            self.logger.error(f"Error checking service status '{service_id}': {error}")
+            return False
+
+    def wait_for_service_ready(self, service_id: str, timeout: int = 300) -> bool:
+        """Várakozás amíg a szolgáltatás futó állapotba kerül.
+
+        Args:
+            service_id: Service ID vagy név
+            timeout: Maximum várakozási idő másodpercekben
+
+        Returns:
+            bool: True ha a szolgáltatás futó állapotba került, False timeout esetén
+        """
+        self.logger.info(f"Waiting for service to become ready: {service_id}")
+
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            if self.is_service_running(service_id):
+                self.logger.info(f"Service is ready: {service_id}")
+                return True
+
+            # Random sleep to avoid overwhelming the API
+            sleep_time = random.uniform(0.5, 2.0)
+            time.sleep(sleep_time)
+
+        self.logger.warning(f"Service did not become ready within {timeout}s: {service_id}")
+        return False
+
+    def get_service_tasks(self, service_id: str) -> List[Dict[str, Any]]:
+        """Szolgáltatás task-jainak lekérése.
+
+        Args:
+            service_id: Service ID vagy név
+
+        Returns:
+            List[Dict]: Service task információk listája
+
+        Raises:
+            BlackAntDockerError: Ha a service nem található vagy API hiba
+        """
+        try:
+            service = self.get_service(service_id)
+            if service:
+                tasks = service.tasks()
+                self.logger.debug(f"Found {len(tasks)} tasks for service: {service_id}")
+                return tasks
+            else:
+                raise BlackAntDockerError(f"Service not found: {service_id}")
+
+        except APIError as api_error:
+            error_msg = f"Error getting tasks for service '{service_id}': {api_error}"
+            self.logger.error(error_msg)
+            raise BlackAntDockerError(error_msg) from api_error
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - cleanup resources."""
+        if hasattr(self.__docker_client, "close"):
+            self.__docker_client.close()