digitalhub 0.14.0b5__py3-none-any.whl → 0.14.9__py3-none-any.whl

digitalhub/stores/client/http_handler.py

@@ -0,0 +1,152 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from requests import request
+
+from digitalhub.stores.client.configurator import ClientConfigurator
+from digitalhub.stores.client.response_processor import ResponseProcessor
+from digitalhub.utils.exceptions import BackendError
+
+# Default timeout for requests (in seconds)
+DEFAULT_TIMEOUT = 60
+
+
+class HttpRequestHandler:
+    """
+    Handles HTTP request execution for DHCore client.
+
+    Encapsulates all HTTP communication logic including request execution,
+    automatic token refresh on authentication failures, and response processing.
+    Works in coordination with configurator for authentication and response
+    processor for parsing.
+    """
+
+    def __init__(self) -> None:
+        self._configurator = ClientConfigurator()
+        self._response_processor = ResponseProcessor()
+
+    def prepare_request(self, method: str, api: str, **kwargs) -> dict:
+        """
+        Execute API call with full URL construction and authentication.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method type (GET, POST, PUT, DELETE, etc.).
+        api : str
+            API endpoint path to call.
+        **kwargs : dict
+            Additional HTTP request arguments.
+
+        Returns
+        -------
+        dict
+            Response from the API call.
+        """
+        full_kwargs = self._set_auth(**kwargs)
+        url = self._build_url(api)
+        return self._execute_request(method, url, **full_kwargs)
+
+    def _execute_request(
+        self,
+        method: str,
+        url: str,
+        **kwargs,
+    ) -> dict:
+        """
+        Execute HTTP request with automatic handling.
+
+        Sends HTTP request with authentication, handles token refresh on 401 errors,
+        validates API version compatibility, and parses response. Uses 60-second
+        timeout by default.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method (GET, POST, PUT, DELETE, etc.).
+        url : str
+            Complete URL to request.
+        **kwargs : dict
+            Additional HTTP request arguments (headers, params, data, etc.).
+
+        Returns
+        -------
+        dict
+            Parsed response body as dictionary.
+        """
+        # Execute HTTP request
+        response = request(method, url, timeout=DEFAULT_TIMEOUT, **kwargs)
+
+        # Process response (version check, error parsing, dictify)
+        try:
+            return self._response_processor.process(response)
+        except BackendError as e:
+            # Handle authentication errors with token refresh
+            if response.status_code == 401 and self._configurator.evaluate_refresh():
+                kwargs = self._configurator.get_auth_parameters(kwargs)
+                return self._execute_request(method, url, **kwargs)
+            raise e
+
+    def _set_auth(self, **kwargs) -> dict:
+        """
+        Prepare kwargs with authentication parameters.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Request parameters to augment with authentication.
+
+        Returns
+        -------
+        dict
+            kwargs enhanced with authentication parameters.
+        """
+        return self._configurator.get_auth_parameters(kwargs)
+
+    def _build_url(self, api: str) -> str:
+        """
+        Build complete URL for API call.
+
+        Combines configured endpoint with API path, automatically removing
+        leading slashes for proper URL construction.
+
+        Parameters
+        ----------
+        api : str
+            API endpoint path. Leading slashes are automatically handled.
+
+        Returns
+        -------
+        str
+            Complete URL for the API call.
+        """
+        endpoint = self._configurator.get_endpoint()
+        return f"{endpoint}/{api.removeprefix('/')}"
+
+    ###############################
+    # Utility methods
+    ###############################
+
+    def refresh_token(self) -> None:
+        """
+        Manually trigger OAuth2 token refresh.
+        """
+        self._configurator.evaluate_refresh()
+
+    def get_credentials_and_config(self) -> dict:
+        """
+        Get current authentication credentials and configuration.
+
+        Returns
+        -------
+        dict
+            Current authentication credentials and configuration.
+        """
+        creds = self._configurator.get_credentials_and_config()
+
+        # Test connection to ensure validity
+        self.prepare_request("GET", "/api/auth")
+        return creds

digitalhub/stores/client/{_base/key_builder.py → key_builder.py}

@@ -4,9 +4,7 @@
 
 from __future__ import annotations
 
-from abc import abstractmethod
-
-from digitalhub.stores.client._base.enums import ApiCategories
+from digitalhub.stores.client.enums import ApiCategories
 
 
 class ClientKeyBuilder:
@@ -36,7 +34,6 @@ class ClientKeyBuilder:
             return self.base_entity_key(*args, **kwargs)
         return self.context_entity_key(*args, **kwargs)
 
-    @abstractmethod
     def base_entity_key(self, entity_id: str) -> str:
         """
         Build for base entity key.
@@ -44,15 +41,15 @@ class ClientKeyBuilder:
         Parameters
         ----------
         entity_id : str
-            The entity identifier.
+            Entity id.
 
         Returns
         -------
         str
-            The formatted base entity key.
+            Key.
         """
+        return f"store://{entity_id}"
 
-    @abstractmethod
     def context_entity_key(
         self,
         project: str,
@@ -67,18 +64,21 @@ class ClientKeyBuilder:
         Parameters
         ----------
         project : str
-            The project name.
+            Project name.
         entity_type : str
-            The entity type.
+            Entity type.
         entity_kind : str
-            The entity kind.
+            Entity kind.
         entity_name : str
-            The entity name.
-        entity_id : str, optional
-            The entity identifier. If None, key will not include version.
+            Entity name.
+        entity_id : str
+            Entity ID.
 
         Returns
         -------
         str
-            The formatted context entity key.
+            Key.
         """
+        if entity_id is None:
+            return f"store://{project}/{entity_type}/{entity_kind}/{entity_name}"
+        return f"store://{project}/{entity_type}/{entity_kind}/{entity_name}:{entity_id}"

digitalhub/stores/client/{dhcore/params_builder.py → params_builder.py}

@@ -4,15 +4,16 @@
 
 from __future__ import annotations
 
-from digitalhub.stores.client._base.enums import ApiCategories, BackendOperations
-from digitalhub.stores.client._base.params_builder import ClientParametersBuilder
+from typing import Any
+
+from digitalhub.stores.client.enums import ApiCategories, BackendOperations
 
 DEFAULT_START_PAGE = 0
 DEFAULT_SIZE = 25
 DEFAULT_SORT = "metadata.updated,DESC"
 
 
-class ClientDHCoreParametersBuilder(ClientParametersBuilder):
+class ClientParametersBuilder:
     """
     Parameter builder for DHCore client API calls.
 
@@ -22,15 +23,6 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
     within projects). Supports query parameter formatting, search filter
     construction for Solr-based searches, cascade deletion options,
     versioning parameters, and entity sharing parameters.
-
-    Methods
-    -------
-    build_parameters(category, operation, **kwargs)
-        Main entry point for parameter building based on API category.
-    build_parameters_base(operation, **kwargs)
-        Builds parameters for base-level API operations.
-    build_parameters_context(operation, **kwargs)
-        Builds parameters for context-level API operations.
     """
 
     def build_parameters(self, category: str, operation: str, **kwargs) -> dict:
@@ -236,6 +228,53 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
 
         return kwargs
 
+    @staticmethod
+    def _ensure_params(**kwargs) -> dict:
+        """
+        Initialize parameter dictionary with query parameters structure.
+
+        Ensures parameter dictionary has 'params' key for HTTP query parameters,
+        guaranteeing consistent structure for all parameter building methods.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Parameters dictionary with guaranteed 'params' key containing
+            empty dict if not already present.
+        """
+        if "params" not in kwargs:
+            kwargs["params"] = {}
+        return kwargs
+
+    @staticmethod
+    def _add_param(key: str, value: Any | None, **kwargs) -> dict:
+        """
+        Add a single query parameter to kwargs.
+
+        Parameters
+        ----------
+        key : str
+            Parameter key.
+        value : Any
+            Parameter value.
+        **kwargs : dict
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
+
+        Returns
+        -------
+        dict
+            Parameters dictionary with added key-value pair in 'params'.
+        """
+        kwargs["params"][key] = value
+        return kwargs
+
     @staticmethod
     def read_page_number(**kwargs) -> int:
         """

digitalhub/stores/client/response_processor.py

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+from warnings import warn
+
+from requests.exceptions import JSONDecodeError
+
+from digitalhub.stores.client.error_parser import ErrorParser
+from digitalhub.utils.exceptions import BackendError, ClientError
+
+if typing.TYPE_CHECKING:
+    from requests import Response
+
+
+# API levels that are supported
+MAX_API_LEVEL = 20
+MIN_API_LEVEL = 14
+LIB_VERSION = 14
+
+
+class ResponseProcessor:
+    """
+    Processes and validates HTTP responses from DHCore backend.
+
+    Handles API version validation, error parsing, and response body parsing
+    to dictionary. Supports API versions {MIN_API_LEVEL} to {MAX_API_LEVEL}.
+    """
+
+    def __init__(self) -> None:
+        self._error_parser = ErrorParser()
+
+    def process(self, response: Response) -> dict:
+        """
+        Process HTTP response with validation and parsing.
+
+        Performs API version compatibility check, error parsing for failed
+        responses, and JSON deserialization.
+
+        Parameters
+        ----------
+        response : Response
+            HTTP response object from backend.
+
+        Returns
+        -------
+        dict
+            Parsed response body as dictionary.
+        """
+        self._check_api_version(response)
+        self._error_parser.parse(response)
+        return self._parse_json(response)
+
+    def _check_api_version(self, response: Response) -> None:
+        """
+        Validate DHCore API version compatibility.
+
+        Checks backend API version against supported range and warns if backend
+        version is newer than library. Supported: {MIN_API_LEVEL} to {MAX_API_LEVEL}.
+
+        Parameters
+        ----------
+        response : Response
+            HTTP response containing X-Api-Level header.
+        """
+        if "X-Api-Level" not in response.headers:
+            return
+
+        core_api_level = int(response.headers["X-Api-Level"])
+        if not (MIN_API_LEVEL <= core_api_level <= MAX_API_LEVEL):
+            raise ClientError("Backend API level not supported.")
+
+        if LIB_VERSION < core_api_level:
+            warn("Backend API level is higher than library version. You should consider updating the library.")
+
+    @staticmethod
+    def _parse_json(response: Response) -> dict:
+        """
+        Parse HTTP response body to dictionary.
+
+        Converts JSON response to Python dictionary, treating empty responses
+        as valid and returning empty dict.
+
+        Parameters
+        ----------
+        response : Response
+            HTTP response object to parse.
+
+        Returns
+        -------
+        dict
+            Parsed response body as dictionary, or empty dict if body is empty.
+        """
+        try:
+            return response.json()
+        except JSONDecodeError:
+            if response.text == "":
+                return {}
+            raise BackendError("Backend response could not be parsed.")

digitalhub/stores/client/utils.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from digitalhub.stores.client.builder import get_client
+
+
+def refresh_token() -> None:
+    """
+    Refresh the current OAuth2 access token.
+
+    Uses the refresh token stored in client configuration to obtain a new
+    access token. Requires OAuth2 authentication configuration.
+
+
+    Raises
+    ------
+    ClientError
+        If client not properly configured or token refresh fails.
+    """
+    get_client().refresh_token()
+
+
+def get_credentials_and_config() -> dict:
+    """
+    Get current client credentials and configuration.
+
+    Returns
+    -------
+    dict
+        Current client credentials and configuration details.
+    """
+    return get_client().get_credentials_and_config()

digitalhub/stores/{credentials → configurator}/api.py

@@ -4,23 +4,19 @@
 
 from __future__ import annotations
 
-from digitalhub.stores.credentials.handler import creds_handler
+from digitalhub.stores.configurator.configurator import configurator
 
 
-def set_current_profile(environment: str) -> None:
+def set_current_profile(profile: str) -> None:
     """
     Set the current credentials profile.
 
     Parameters
     ----------
-    environment : str
+    profile : str
         Name of the credentials profile to set.
-
-    Returns
-    -------
-    None
     """
-    creds_handler.set_current_profile(environment)
+    configurator.set_current_profile(profile)
 
 
 def get_current_profile() -> str:
@@ -32,4 +28,4 @@ def get_current_profile() -> str:
     str
         Name of the current credentials profile.
     """
-    return creds_handler.get_current_profile()
+    return configurator.get_current_profile()

digitalhub/stores/configurator/configurator.py

@@ -0,0 +1,123 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from digitalhub.stores.configurator.handler import ConfigurationHandler
+
+
+class Configurator:
+    """
+    Configurator class for configuration and credentials management.
+    """
+
+    def __init__(self):
+        self._handler = ConfigurationHandler()
+        self._reload_from_env = False
+
+    ##############################
+    # Configuration
+    ##############################
+
+    def get_configuration(self) -> dict:
+        """
+        Retrieve the current configuration.
+
+        Returns
+        -------
+        dict
+            Dictionary of configuration variables.
+        """
+        return self._handler.get_configuration()
+
+    ##############################
+    # Credentials
+    ##############################
+
+    def get_credentials(self) -> dict:
+        """
+        Retrieve the current credentials.
+
+        Returns
+        -------
+        dict
+            Dictionary of credentials.
+        """
+        return self._handler.get_credentials()
+
+    def eval_retry(self) -> bool:
+        """
+        Evaluate credentials reload based on retry logic.
+
+        Returns
+        -------
+        bool
+            True if a retry action was performed, otherwise False.
+        """
+        current_creds = self.get_credentials()
+        reread_creds = self._handler.load_credentials()
+
+        # Compare cached and file credentials.
+        # If different, reload in cache.
+        if current_creds != reread_creds:
+            self.reload_credentials()
+            return True
+
+        # Check if we need to reload from env only
+        if not self._reload_from_env:
+            self._handler.reload_credentials_from_env()
+            self._reload_from_env = True
+            return True
+
+        return False
+
+    def reload_credentials(self) -> None:
+        """
+        Reload credentials from environment and file.
+        """
+        self._handler.reload_credentials()
+
+    ###############################
+    # Profile methods
+    ###############################
+
+    def set_current_profile(self, profile: str) -> None:
+        """
+        Set the current profile.
+
+        Parameters
+        ----------
+        profile : str
+            Name of the profile to set.
+        """
+        self._handler.set_current_profile(profile)
+
+    ################################
+    # Other methods
+    ################################
+
+    def write_file(self, variables: dict) -> None:
+        """
+        Write the current configuration and credentials to file.
+
+        Parameters
+        ----------
+        variables : dict
+            Dictionary of variables to write.
+        """
+        self._handler.write_file(variables)
+
+    def get_config_creds(self) -> dict:
+        """
+        Get merged configuration and credentials.
+
+        Returns
+        -------
+        dict
+            Merged configuration and credentials dictionary.
+        """
+        return {**self.get_configuration(), **self.get_credentials()}
+
+
+configurator = Configurator()

digitalhub/stores/{credentials → configurator}/enums.py

@@ -32,26 +32,20 @@ class SetCreds(Enum):
     DH_PROFILE = "DH_NAME"
 
 
-class CredsEnvVar(Enum):
+class ConfigurationVars(Enum):
     """
-    Supported credential environment variables.
+    List of supported configuration variables.
     """
 
     # S3
     S3_ENDPOINT_URL = "AWS_ENDPOINT_URL"
-    S3_ACCESS_KEY_ID = "AWS_ACCESS_KEY_ID"
-    S3_SECRET_ACCESS_KEY = "AWS_SECRET_ACCESS_KEY"
-    S3_SESSION_TOKEN = "AWS_SESSION_TOKEN"
     S3_REGION = "AWS_REGION"
     S3_SIGNATURE_VERSION = "S3_SIGNATURE_VERSION"
-    S3_CREDENTIALS_EXPIRATION = "AWS_CREDENTIALS_EXPIRATION"
     S3_PATH_STYLE = "S3_PATH_STYLE"
 
     # SQL
     DB_HOST = "DB_HOST"
     DB_PORT = "DB_PORT"
-    DB_USERNAME = "DB_USERNAME"
-    DB_PASSWORD = "DB_PASSWORD"
     DB_DATABASE = "DB_DATABASE"
     DB_PLATFORM = "DB_PLATFORM"
     DB_PG_SCHEMA = "DB_SCHEMA"
@@ -59,10 +53,32 @@ class CredsEnvVar(Enum):
     # DHCORE
     DHCORE_ENDPOINT = "DHCORE_ENDPOINT"
     DHCORE_ISSUER = "DHCORE_ISSUER"
+    DHCORE_WORKFLOW_IMAGE = "DHCORE_WORKFLOW_IMAGE"
+    DHCORE_CLIENT_ID = "DHCORE_CLIENT_ID"
+    DEFAULT_FILES_STORE = "DHCORE_DEFAULT_FILES_STORE"
+
+    # OAUTH2
+    OAUTH2_TOKEN_ENDPOINT = "OAUTH2_TOKEN_ENDPOINT"
+
+
+class CredentialsVars(Enum):
+    """
+    List of supported credential variables.
+    """
+
+    # S3
+    S3_ACCESS_KEY_ID = "AWS_ACCESS_KEY_ID"
+    S3_SECRET_ACCESS_KEY = "AWS_SECRET_ACCESS_KEY"
+    S3_SESSION_TOKEN = "AWS_SESSION_TOKEN"
+    S3_CREDENTIALS_EXPIRATION = "AWS_CREDENTIALS_EXPIRATION"
+
+    # SQL
+    DB_USERNAME = "DB_USERNAME"
+    DB_PASSWORD = "DB_PASSWORD"
+
+    # DHCORE
     DHCORE_USER = "DHCORE_USER"
     DHCORE_PASSWORD = "DHCORE_PASSWORD"
-    DHCORE_CLIENT_ID = "DHCORE_CLIENT_ID"
     DHCORE_ACCESS_TOKEN = "DHCORE_ACCESS_TOKEN"
     DHCORE_REFRESH_TOKEN = "DHCORE_REFRESH_TOKEN"
     DHCORE_PERSONAL_ACCESS_TOKEN = "DHCORE_PERSONAL_ACCESS_TOKEN"
-    DHCORE_WORKFLOW_IMAGE = "DHCORE_WORKFLOW_IMAGE"