novastack-utils 1.0.0__tar.gz

novastack_utils-1.0.0/.gitignore

@@ -0,0 +1,85 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+#IDE
+.DS_Store
+.idea
+.vscode
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Mkdocs documentation
+docs/_build/
+docs/api_reference/site/
+
+# Ruff
+.ruff_cache/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/

novastack_utils-1.0.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: novastack-utils
+Version: 1.0.0
+Summary: This library contains utilities used across various packages.
+Project-URL: Repository, https://github.com/novastack-project/novastack/tree/main/novastack-utils
+Author-email: Leonardo Furnielis <leonardofurnielis@outlook.com>
+License: Apache-2.0
+Requires-Python: <3.14,>=3.11
+Requires-Dist: httpx<1.0.0,>=0.28.1
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<2.0.0,>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-mock<4.0.0,>=3.15.1; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=9.0.3; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.15.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Novastack utils
+
+This library contains utils utilities used across various packages.
+
+## Installation 
+
+```bash
+pip install novastack-utils
+```

novastack_utils-1.0.0/README.md

@@ -0,0 +1,9 @@
+# Novastack utils
+
+This library contains utils utilities used across various packages.
+
+## Installation 
+
+```bash
+pip install novastack-utils
+```

novastack_utils-1.0.0/novastack_utils/__init__.py

@@ -0,0 +1,6 @@
+from novastack_utils.utils import validate_enum, validate_type
+
+__all__ = [
+    "validate_enum",
+    "validate_type",
+]

novastack_utils-1.0.0/novastack_utils/http/__init__.py

@@ -0,0 +1,5 @@
+from novastack_utils.http.base import HttpService
+
+__all__ = [
+    "HttpService",
+]

novastack_utils-1.0.0/novastack_utils/http/authenticators/__init__.py

@@ -0,0 +1,21 @@
+from novastack_utils.http.authenticators.basic_authenticator import (
+    BasicAuthenticator,
+)
+from novastack_utils.http.authenticators.ibm_iam_authenticator import (
+    IBMIAMAuthenticator,
+)
+from novastack_utils.http.authenticators.no_auth_authenticator import (
+    NoAuthAuthenticator,
+)
+from novastack_utils.http.authenticators.oauth2_authenticator import (
+    OAuth2Authenticator,
+    OAuth2GrantType,
+)
+
+__all__ = [
+    "BasicAuthenticator",
+    "IBMIAMAuthenticator",
+    "NoAuthAuthenticator",
+    "OAuth2Authenticator",
+    "OAuth2GrantType",
+]

novastack_utils-1.0.0/novastack_utils/http/authenticators/base.py

@@ -0,0 +1,22 @@
+from abc import ABC, abstractmethod
+
+from pydantic import BaseModel
+
+
+class BaseAuthenticator(BaseModel, ABC):
+    """
+    Abstract base class for authentication.
+
+    All authentication strategies must implement the authenticate method
+    to provide authentication headers for HTTP requests.
+    """
+
+    model_config = {
+        "arbitrary_types_allowed": True,
+        "validate_assignment": True,
+        "validate_default": True,
+    }
+
+    @abstractmethod
+    def authenticate(self) -> dict[str, str]:
+        """Authenticate and return headers to be added to requests."""

novastack_utils-1.0.0/novastack_utils/http/authenticators/basic_authenticator.py

@@ -0,0 +1,37 @@
+import base64
+
+from pydantic import Field, SecretStr
+
+from novastack_utils.http.authenticators.base import BaseAuthenticator
+from novastack_utils.http.exceptions import HttpAuthenticationError
+
+
+class BasicAuthenticator(BaseAuthenticator):
+    """
+    HTTP Basic Authentication.
+
+    Implements standard HTTP Basic authentication using Base64 encoding
+    of username and password credentials.
+    """
+
+    username: str = Field(..., min_length=1, description="Username for authentication")
+    password: SecretStr = Field(..., description="Password for authentication")
+
+    def authenticate(self) -> dict[str, str]:
+        """Generate Basic authentication header."""
+        try:
+            password_value = self.password.get_secret_value()
+
+            # Combine username and password
+            credentials = f"{self.username}:{password_value}"
+
+            # Encode to Base64
+            encoded = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")
+
+            # Return Authorization header
+            return {"Authorization": f"Basic {encoded}"}
+
+        except Exception as e:
+            raise HttpAuthenticationError(
+                f"Failed to generate BasicAuthenticator header: {e}"
+            )

novastack_utils-1.0.0/novastack_utils/http/authenticators/ibm_iam_authenticator.py

@@ -0,0 +1,99 @@
+from datetime import datetime, timedelta
+
+import httpx
+from pydantic import Field, PrivateAttr, SecretStr
+
+from novastack_utils.http.authenticators.base import BaseAuthenticator
+from novastack_utils.http.exceptions import HttpAuthenticationError
+
+
+class IBMIAMAuthenticator(BaseAuthenticator):
+    """
+    IBM Cloud IAM authentication.
+
+    Uses IBM Cloud API Key to obtain access tokens from IBM IAM service.
+    Automatically manages token lifecycle including expiration tracking and refresh.
+    """
+
+    api_key: SecretStr = Field(..., description="IBM Cloud API Key")
+    token_url: str = Field(
+        default="https://iam.cloud.ibm.com/identity/token",
+        description="IBM IAM token endpoint URL",
+    )
+
+    _access_token: str | None = PrivateAttr(default=None)
+    _token_type: str = PrivateAttr(default="Bearer")
+    _expires_at: datetime | None = PrivateAttr(default=None)
+    _refresh_token: str | None = PrivateAttr(default=None)
+
+    def authenticate(self) -> dict[str, str]:
+        """
+        Get authentication headers with valid access token.
+
+        Automatically refreshes token if expired.
+        """
+        # Check if token needs refresh
+        if self.is_expired():
+            self._get_access_token()
+
+        return {"Authorization": f"{self._token_type} {self._access_token}"}
+
+    def is_expired(self) -> bool:
+        """Check if access token is expired."""
+        if not self._access_token or not self._expires_at:
+            return True
+
+        # Consider token expired if it expires within 60 seconds
+        buffer = timedelta(seconds=60)
+        return datetime.now() >= (self._expires_at - buffer)
+
+    def _get_access_token(self) -> None:
+        """Get IBM IAM access token."""
+        try:
+            data = {
+                "grant_type": "urn:ibm:params:oauth:grant-type:apikey",
+                "apikey": self.api_key.get_secret_value(),
+            }
+
+            # Make token request
+            response = httpx.post(
+                self.token_url,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            # Raise for any HTTP error status
+            response.raise_for_status()
+
+            token_data = response.json()
+
+            self._access_token = token_data.get("access_token")
+            if not self._access_token:
+                raise HttpAuthenticationError(
+                    "No 'access_token' in IBM IAM token response"
+                )
+
+            self._token_type = token_data.get("token_type", "Bearer")
+            self._refresh_token = token_data.get("refresh_token")
+
+            # Calculate expiration time
+            expires_in = token_data.get("expires_in")
+            if expires_in:
+                self._expires_at = datetime.now() + timedelta(seconds=int(expires_in))
+            else:
+                # Default to 1 hour if not provided
+                self._expires_at = datetime.now() + timedelta(hours=1)
+
+        except httpx.HTTPStatusError as e:
+            error_detail = e.response.text
+            raise HttpAuthenticationError(
+                f"IBM IAM token request failed with status {e.response.status_code}: {error_detail}"
+            )
+        except httpx.TimeoutException as e:
+            raise HttpAuthenticationError(f"IBM IAM token request timed out: {e}")
+        except httpx.ConnectError as e:
+            raise HttpAuthenticationError(f"Failed to connect to IBM IAM endpoint: {e}")
+        except HttpAuthenticationError:
+            raise
+        except Exception as e:
+            raise HttpAuthenticationError(f"Failed to obtain IBM IAM token: {e}")

novastack_utils-1.0.0/novastack_utils/http/authenticators/no_auth_authenticator.py

@@ -0,0 +1,11 @@
+from novastack_utils.http.authenticators.base import BaseAuthenticator
+
+
+class NoAuthAuthenticator(BaseAuthenticator):
+    """
+    This is the default authentication when no authentication is required.
+    It returns empty dict, adding no authentication headers to requests.
+    """
+
+    def authenticate(self) -> dict[str, str]:
+        return {}

novastack_utils-1.0.0/novastack_utils/http/authenticators/oauth2_authenticator.py

@@ -0,0 +1,200 @@
+from datetime import datetime, timedelta
+from typing import Any
+
+import httpx
+from pydantic import Field, PrivateAttr, SecretStr, field_validator
+
+from novastack_utils import validate_enum
+from novastack_utils.http.authenticators.base import BaseAuthenticator
+from novastack_utils.http.exceptions import HttpAuthenticationError
+
+
+class OAuth2GrantType:
+    """
+    Supported OAuth2 grant type.
+
+    Attributes:
+        CLIENT_CREDENTIALS (str): "client_credentials"
+        PASSWORD (str):"password"
+        AUTHORIZATION_CODE (str): "authorization_code"
+        REFRESH_TOKEN (str): "refresh_token"
+    """
+
+    CLIENT_CREDENTIALS = "client_credentials"
+    PASSWORD = "password"
+    AUTHORIZATION_CODE = "authorization_code"
+    REFRESH_TOKEN = "refresh_token"
+
+
+class OAuth2Authenticator(BaseAuthenticator):
+    """
+    OAuth 2.0 authentication.
+
+    Automatically manages token lifecycle including expiration tracking and refresh.
+    """
+
+    token_url: str = Field(..., description="OAuth2 token endpoint URL")
+    client_id: str = Field(..., min_length=1, description="OAuth2 client ID")
+    client_secret: SecretStr = Field(..., description="OAuth2 client secret")
+    grant_type: str = Field(
+        default=OAuth2GrantType.CLIENT_CREDENTIALS, description="OAuth2 grant type"
+    )
+    username: str | None = Field(
+        default=None, description="Username for password grant_type"
+    )
+    password: SecretStr | None = Field(
+        default=None, description="Password for password grant_type"
+    )
+    scope: str | None = Field(
+        default=None, description="Optional OAuth scope to request"
+    )
+
+    _access_token: str | None = PrivateAttr(default=None)
+    _token_type: str = PrivateAttr(default="Bearer")
+    _expires_at: datetime | None = PrivateAttr(default=None)
+    _refresh_token: str | None = PrivateAttr(default=None)
+
+    @field_validator("grant_type")
+    def _validate_grant_type(cls, v):
+        validate_enum(el=v, el_name="grant_type", expected_enum=OAuth2GrantType)
+        return v
+
+    def model_post_init(self, __context: Any) -> None:  # noqa: PYI063
+        if self.grant_type == OAuth2GrantType.PASSWORD:
+            if not self.username or not self.password:
+                raise HttpAuthenticationError(
+                    "'username' and 'password' are required for PASSWORD grant_type."
+                )
+
+    def authenticate(self) -> dict[str, str]:
+        """
+        Get authentication headers with valid access token.
+
+        Automatically refreshes token if expired.
+        """
+        # Check if token needs refresh
+        if self.is_expired():
+            self.refresh_token()
+
+        # If still no token, get a new one
+        if not self._access_token:
+            self._get_access_token()
+
+        return {"Authorization": f"{self._token_type} {self._access_token}"}
+
+    def refresh_token(self) -> None:
+        """
+        Refresh OAuth2 token.
+
+        Attempts to use refresh token if available, otherwise obtains new token.
+        """
+        # If we have a refresh token, try to use it
+        if self._refresh_token:
+            try:
+                self._get_access_token(use_refresh_token=True)
+                return
+            except HttpAuthenticationError:
+                # If refresh fails, fall through to get new token
+                pass
+
+        self._get_access_token()
+
+    def is_expired(self) -> bool:
+        """Check if access token is expired."""
+        if not self._access_token or not self._expires_at:
+            return True
+
+        # Consider token expired if it expires within 60 seconds
+        buffer = timedelta(seconds=60)
+        return datetime.now() >= (self._expires_at - buffer)
+
+    def _get_access_token(self, use_refresh_token: bool = False) -> None:
+        """
+        Get OAuth2 access token from token endpoint.
+
+        Args:
+            use_refresh_token: Whether to use refresh token grant
+        """
+        try:
+            # Build request payload
+            data = self._build_token_request_data(use_refresh_token)
+
+            # Make token request
+            response = httpx.post(
+                self.token_url,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            # Raise for any HTTP error status
+            response.raise_for_status()
+
+            token_data = response.json()
+
+            self._access_token = token_data.get("access_token")
+            if not self._access_token:
+                raise HttpAuthenticationError(
+                    "No 'access_token' in authenticator response"
+                )
+
+            self._token_type = token_data.get("token_type", "Bearer")
+            self._refresh_token = token_data.get("refresh_token")
+
+            # Calculate expiration time
+            expires_in = token_data.get("expires_in")
+            if expires_in:
+                self._expires_at = datetime.now() + timedelta(seconds=int(expires_in))
+            else:
+                # Default to 1 hour if not provided
+                self._expires_at = datetime.now() + timedelta(hours=1)
+
+        except httpx.HTTPStatusError as e:
+            error_detail = e.response.text
+            raise HttpAuthenticationError(
+                f"Token request failed with status {e.response.status_code}: {error_detail}"
+            )
+        except httpx.TimeoutException as e:
+            raise HttpAuthenticationError(f"Token request timed out: {e}")
+        except httpx.ConnectError as e:
+            raise HttpAuthenticationError(f"Failed to connect to token endpoint: {e}")
+        except HttpAuthenticationError:
+            raise
+        except Exception as e:
+            raise HttpAuthenticationError(f"Failed to get OAuth2 token: {e}")
+
+    def _build_token_request_data(self, use_refresh_token: bool) -> dict[str, str]:
+        """
+        Build OAuth2 token request payload.
+
+        Args:
+            use_refresh_token: Whether to use refresh token grant
+        """
+        base_data = {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret.get_secret_value(),
+        }
+
+        if use_refresh_token and self._refresh_token:
+            data = {
+                "grant_type": OAuth2GrantType.REFRESH_TOKEN,
+                "refresh_token": self._refresh_token,
+                **base_data,
+            }
+        elif self.grant_type == OAuth2GrantType.PASSWORD:
+            data = {
+                "grant_type": self.grant_type,
+                "username": self.username,
+                "password": self.password.get_secret_value() if self.password else None,
+                **base_data,
+            }
+        else:
+            data = {
+                "grant_type": self.grant_type,
+                **base_data,
+            }
+
+        # Add optional scope
+        if self.scope:
+            data["scope"] = self.scope
+
+        return data

novastack_utils-1.0.0/novastack_utils/http/base.py

@@ -0,0 +1,330 @@
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, Field, PrivateAttr
+
+from novastack_utils.http.authenticators import NoAuthAuthenticator
+from novastack_utils.http.authenticators.base import BaseAuthenticator
+from novastack_utils.http.exceptions import (
+    HttpConnectionError,
+    HttpRequestError,
+    HttpRequestTimeoutError,
+)
+from novastack_utils.http.types import HttpResponse
+
+
+class HttpService(BaseModel):
+    """
+    Enterprise-grade HTTP service with authentication and connection pooling.
+
+    Provides both synchronous and asynchronous HTTP methods with pluggable
+    authentication strategies.
+    """
+
+    model_config = {
+        "arbitrary_types_allowed": True,
+        "validate_assignment": True,
+        "validate_default": True,
+    }
+
+    base_url: str = Field(..., description="Base URL for all requests")
+    timeout: float = Field(default=30.0, gt=0, description="Request timeout in seconds")
+    verify_ssl: bool = Field(
+        default=True, description="Whether to verify SSL certificates"
+    )
+    headers: dict[str, str] = Field(
+        default_factory=dict, description="Default headers for all requests"
+    )
+    authenticator: BaseAuthenticator = Field(
+        default_factory=NoAuthAuthenticator, description="Authentication strategy."
+    )
+
+    _client: httpx.Client = PrivateAttr()
+    _async_client: httpx.AsyncClient = PrivateAttr()
+
+    def model_post_init(self, __context: Any) -> None:  # noqa: PYI063
+        """Initialize HTTP clients after model creation."""
+        # Initialize sync client
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            verify=self.verify_ssl,
+            headers=self.headers,
+        )
+
+        # Initialize async client
+        self._async_client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            verify=self.verify_ssl,
+            headers=self.headers,
+        )
+
+    def _prepare_headers(self, headers: dict[str, str] | None = None) -> dict[str, str]:
+        """
+        Prepare request headers with authentication.
+
+        Args:
+            headers: Additional headers to include
+        """
+        combined_headers = self.headers.copy()
+        if headers:
+            combined_headers.update(headers)
+
+        # Apply authentication if strategy is provided
+        if self.authenticator:
+            auth_headers = self.authenticator.authenticate()
+            combined_headers.update(auth_headers)
+
+        return combined_headers
+
+    def _handle_response(self, response: httpx.Response) -> HttpResponse:
+        """
+        Handle HTTP response and convert to HttpResponse object.
+
+        Args:
+            response: httpx response object
+        """
+        return HttpResponse(
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            content=response.content,
+            url=str(response.url),
+        )
+
+    def get(
+        self,
+        url: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResponse:
+        """
+        Perform synchronous GET request.
+
+        Args:
+            url: Request url
+            params: Query parameters
+            headers: Additional headers
+        """
+        try:
+            prepared_headers = self._prepare_headers(headers)
+            response = self._client.get(url, params=params, headers=prepared_headers)
+            return self._handle_response(response)
+
+        except httpx.TimeoutException as e:
+            raise HttpRequestTimeoutError(str(e))
+        except httpx.ConnectError as e:
+            raise HttpConnectionError(f"Failed to connect: {e}")
+        except Exception as e:
+            raise HttpRequestError(f"GET request failed: {e}")
+
+    def post(
+        self,
+        url: str,
+        data: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResponse:
+        """
+        Perform synchronous POST request.
+
+        Args:
+            url: Request url (relative to base_url)
+            data: Form data
+            json: JSON data
+            params: Query parameters
+            headers: Additional headers
+        """
+        try:
+            prepared_headers = self._prepare_headers(headers)
+            response = self._client.post(
+                url, data=data, json=json, params=params, headers=prepared_headers
+            )
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise HttpRequestTimeoutError(str(e))
+        except httpx.ConnectError as e:
+            raise HttpConnectionError(f"Failed to connect: {e}")
+        except Exception as e:
+            raise HttpRequestError(f"POST request failed: {e}")
+
+    def put(
+        self,
+        url: str,
+        data: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResponse:
+        """
+        Perform synchronous PUT request.
+
+        Args:
+            url: Request url (relative to base_url)
+            data: Form data
+            json: JSON data
+            params: Query parameters
+            headers: Additional headers
+        """
+        try:
+            prepared_headers = self._prepare_headers(headers)
+            response = self._client.put(
+                url, data=data, json=json, params=params, headers=prepared_headers
+            )
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise HttpRequestTimeoutError(str(e))
+        except httpx.ConnectError as e:
+            raise HttpConnectionError(f"Failed to connect: {e}")
+        except Exception as e:
+            raise HttpRequestError(f"PUT request failed: {e}")
+
+    def delete(
+        self,
+        url: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResponse:
+        """
+        Perform synchronous DELETE request.
+
+        Args:
+            url: Request url (relative to base_url)
+            params: Query parameters
+            headers: Additional headers
+        """
+        try:
+            prepared_headers = self._prepare_headers(headers)
+            response = self._client.delete(url, params=params, headers=prepared_headers)
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise HttpRequestTimeoutError(str(e))
+        except httpx.ConnectError as e:
+            raise HttpConnectionError(f"Failed to connect: {e}")
+        except Exception as e:
+            raise HttpRequestError(f"DELETE request failed: {e}")
+
+    async def aget(
+        self,
+        url: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResponse:
+        """
+        Perform asynchronous GET request.
+
+        Args:
+            url: Request url (relative to base_url)
+            params: Query parameters
+            headers: Additional headers
+        """
+        try:
+            prepared_headers = self._prepare_headers(headers)
+            response = await self._async_client.get(
+                url, params=params, headers=prepared_headers
+            )
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise HttpRequestTimeoutError(str(e))
+        except httpx.ConnectError as e:
+            raise HttpConnectionError(f"Failed to connect: {e}")
+        except Exception as e:
+            raise HttpRequestError(f"GET request failed: {e}")
+
+    async def apost(
+        self,
+        url: str,
+        data: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResponse:
+        """
+        Perform asynchronous POST request.
+
+        Args:
+            url: Request url (relative to base_url)
+            data: Form data
+            json: JSON data
+            params: Query parameters
+            headers: Additional headers
+        """
+        try:
+            prepared_headers = self._prepare_headers(headers)
+            response = await self._async_client.post(
+                url, data=data, json=json, params=params, headers=prepared_headers
+            )
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise HttpRequestTimeoutError(str(e))
+        except httpx.ConnectError as e:
+            raise HttpConnectionError(f"Failed to connect: {e}")
+        except Exception as e:
+            raise HttpRequestError(f"POST request failed: {e}")
+
+    async def aput(
+        self,
+        url: str,
+        data: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResponse:
+        """
+        Perform asynchronous PUT request.
+
+        Args:
+            url: Request url (relative to base_url)
+            data: Form data
+            json: JSON data
+            params: Query parameters
+            headers: Additional headers
+        """
+        try:
+            prepared_headers = self._prepare_headers(headers)
+            response = await self._async_client.put(
+                url, data=data, json=json, params=params, headers=prepared_headers
+            )
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise HttpRequestTimeoutError(str(e))
+        except httpx.ConnectError as e:
+            raise HttpConnectionError(f"Failed to connect: {e}")
+        except Exception as e:
+            raise HttpRequestError(f"PUT request failed: {e}")
+
+    async def adelete(
+        self,
+        url: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResponse:
+        """
+        Perform asynchronous DELETE request.
+
+        Args:
+            url: Request url (relative to base_url)
+            params: Query parameters
+            headers: Additional headers
+        """
+        try:
+            prepared_headers = self._prepare_headers(headers)
+            response = await self._async_client.delete(
+                url, params=params, headers=prepared_headers
+            )
+            return self._handle_response(response)
+        except httpx.TimeoutException as e:
+            raise HttpRequestTimeoutError(str(e))
+        except httpx.ConnectError as e:
+            raise HttpConnectionError(f"Failed to connect: {e}")
+        except Exception as e:
+            raise HttpRequestError(f"DELETE request failed: {e}")
+
+    def close(self) -> None:
+        if self._client:
+            self._client.close()
+
+    async def aclose(self) -> None:
+        if self._async_client:
+            await self._async_client.aclose()

novastack_utils-1.0.0/novastack_utils/http/exceptions.py

@@ -0,0 +1,14 @@
+class HttpRequestError(Exception):
+    """Generic exception for HTTP service errors."""
+
+
+class HttpAuthenticationError(Exception):
+    """Raised when authentication fails."""
+
+
+class HttpRequestTimeoutError(HttpRequestError):
+    """Raised when a request times out."""
+
+
+class HttpConnectionError(HttpRequestError):
+    """Raised when connection to server fails."""

novastack_utils-1.0.0/novastack_utils/http/types.py

@@ -0,0 +1,36 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class HttpRetryConfig(BaseModel):
+    """Configuration for retry behavior."""
+
+    max_retries: int = Field(
+        default=3, ge=0, description="Maximum number of retry attempts"
+    )
+    retry_delay: float = Field(
+        default=1.0, gt=0, description="Delay between retries in seconds"
+    )
+
+
+class HttpResponse(BaseModel):
+    """HTTP Response wrapper."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    status_code: int = Field(..., description="HTTP status code")
+    headers: dict[str, str] = Field(
+        default_factory=dict, description="HTTP Response Headers"
+    )
+    content: bytes = Field(default=b"", description="Raw Response Content")
+    url: str = Field(...)
+
+    def json_dump(self) -> Any:
+        """Parse response content as JSON."""
+        import json
+
+        try:
+            return json.loads(self.content.decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as e:
+            raise ValueError(f"Failed to parse response as JSON: {e}")

novastack_utils-1.0.0/novastack_utils/retry/__init__.py

@@ -0,0 +1,19 @@
+from novastack_utils.retry.decorator import retry
+from novastack_utils.retry.strategies import (
+    retry_if_exception,
+    stop_after_attempt,
+    stop_after_delay,
+    wait_exponential,
+    wait_fixed,
+    wait_random,
+)
+
+__all__ = [
+    "retry",
+    "retry_if_exception",
+    "stop_after_attempt",
+    "stop_after_delay",
+    "wait_exponential",
+    "wait_fixed",
+    "wait_random",
+]

novastack_utils-1.0.0/novastack_utils/retry/decorator.py

@@ -0,0 +1,108 @@
+import asyncio
+import functools
+import time
+from typing import Any, Callable, TypeVar
+
+from novastack_utils.retry.strategies import (
+    retry_if_exception,
+    stop_after_attempt,
+    wait_fixed,
+)
+from novastack_utils.retry.types import (
+    RetryCondition,
+    RetryState,
+    StopCondition,
+    WaitStrategy,
+)
+
+T = TypeVar("T")
+
+
+def _build_retry_state(
+    retry_number: int,
+    elapsed_time: float,
+    last_exception: Exception | None = None,
+) -> RetryState:
+    return RetryState(
+        retry_number=retry_number - 1,
+        elapsed_time=elapsed_time,
+        last_exception=last_exception,
+    )
+
+
+def retry(
+    stop: StopCondition | None = None,
+    when: RetryCondition | None = None,
+    wait: WaitStrategy | None = None,
+    reraise: bool = True,
+) -> Callable[[Callable[..., T]], Callable[..., T | None]]:
+    stop_condition = stop or stop_after_attempt(3)
+    retry_condition = when or retry_if_exception()
+    wait_strategy = wait or wait_fixed(1)
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T | None]:
+        if asyncio.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> T | None:
+                start_time = time.monotonic()
+                retry_number = 0
+
+                while True:
+                    retry_number += 1
+                    try:
+                        return await func(*args, **kwargs)
+                    except Exception as exc:
+                        retry_state = _build_retry_state(
+                            retry_number=retry_number,
+                            elapsed_time=time.monotonic() - start_time,
+                            last_exception=exc,
+                        )
+
+                        if not retry_condition(exc):
+                            if reraise:
+                                raise
+                            return None
+
+                        if stop_condition(retry_state):
+                            if reraise:
+                                raise
+                            return None
+
+                        sleep_time = wait_strategy(retry_state)
+                        await asyncio.sleep(sleep_time)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T | None:
+            start_time = time.monotonic()
+            retry_number = 0
+
+            while True:
+                retry_number += 1
+                try:
+                    return func(*args, **kwargs)
+                except Exception as exc:
+                    retry_state = _build_retry_state(
+                        retry_number=retry_number,
+                        elapsed_time=time.monotonic() - start_time,
+                        last_exception=exc,
+                    )
+
+                    if not retry_condition(exc):
+                        if reraise:
+                            raise
+                        return None
+
+                    if stop_condition(retry_state):
+                        if reraise:
+                            raise
+                        return None
+
+                    sleep_time = wait_strategy(retry_state)
+                    time.sleep(sleep_time)
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator

novastack_utils-1.0.0/novastack_utils/retry/strategies.py

@@ -0,0 +1,115 @@
+import random
+
+from novastack_utils.retry.types import RetryState
+
+
+class _BaseRetryCondition:
+    """Base class for retry predicates."""
+
+    def __call__(self, exception: Exception) -> bool:
+        raise NotImplementedError
+
+
+class _BaseStopConditionBase:
+    """Base class for stop conditions."""
+
+    def __call__(self, retry_state: RetryState) -> bool:
+        raise NotImplementedError
+
+
+class _BaseWaitStrategy:
+    """Base class for wait strategies."""
+
+    def __call__(self, retry_state: RetryState) -> float:
+        raise NotImplementedError
+
+
+class retry_if_exception(_BaseRetryCondition):
+    def __call__(self, exception: Exception) -> bool:
+        return True
+
+
+class stop_after_attempt(_BaseStopConditionBase):
+    def __init__(self, max_retries: int) -> None:
+        if max_retries < 1:
+            raise ValueError(
+                f"Invalid max_retries '{max_retries}' Input should be: greater than or equal to 1."
+            )
+        self.max_retries = max_retries
+
+    def __call__(self, retry_state: RetryState) -> bool:
+        return retry_state.retry_number >= self.max_retries
+
+
+class stop_after_delay(_BaseStopConditionBase):
+    def __init__(self, max_delay: float) -> None:
+        if max_delay < 0:
+            raise ValueError(
+                f"Invalid max_delay '{max_delay}' Input should be: greater than or equal to 0."
+            )
+        self.max_delay = max_delay
+
+    def __call__(self, retry_state: RetryState) -> bool:
+        return retry_state.elapsed_time >= self.max_delay
+
+
+class wait_fixed(_BaseWaitStrategy):
+    def __init__(self, wait: float) -> None:
+        if wait < 0:
+            raise ValueError(
+                f"Invalid wait '{wait}' Input should be: greater than or equal to 0."
+            )
+        self.wait = wait
+
+    def __call__(self, retry_state: RetryState) -> float:
+        return self.wait
+
+
+class wait_exponential(_BaseWaitStrategy):
+    def __init__(
+        self,
+        multiplier: float = 1,
+        min: float = 0,
+        max: float | None = None,
+    ) -> None:
+        if multiplier < 0:
+            raise ValueError(
+                f"Invalid multiplier '{multiplier}' Input should be: greater than or equal to 0."
+            )
+        if min < 0:
+            raise ValueError(
+                f"Invalid min '{min}' Input should be: greater than or equal to 0."
+            )
+        if max is not None and max < min:
+            raise ValueError(
+                f"Invalid max '{max}' Input should be: greater than or equal to min."
+            )
+
+        self.multiplier = multiplier
+        self.min = min
+        self.max = max
+
+    def __call__(self, retry_state: RetryState) -> float:
+        delay = self.multiplier * (2 ** (retry_state.retry_number - 1))
+        delay = delay if delay > self.min else self.min
+        if self.max is not None and delay > self.max:
+            delay = self.max
+        return delay
+
+
+class wait_random(_BaseWaitStrategy):
+    def __init__(self, min: float, max: float) -> None:
+        if min < 0:
+            raise ValueError(
+                f"Invalid min '{min}' Input should be: greater than or equal to 0."
+            )
+        if max < min:
+            raise ValueError(
+                f"Invalid max '{max}' Input should be: greater than or equal to min."
+            )
+
+        self.min = min
+        self.max = max
+
+    def __call__(self, retry_state: RetryState) -> float:
+        return random.uniform(self.min, self.max)

novastack_utils-1.0.0/novastack_utils/retry/types.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(slots=True)
+class RetryState:
+    retry_number: int
+    elapsed_time: float
+    last_exception: Exception | None = None
+
+
+class RetryCondition(Protocol):
+    """Protocol for retry predicates that decide whether an exception is retryable."""
+
+    def __call__(self, exception: Exception) -> bool: ...
+
+
+class StopCondition(Protocol):
+    """Protocol for stop conditions that decide when to stop retrying."""
+
+    def __call__(self, retry_state: RetryState) -> bool: ...
+
+
+class WaitStrategy(Protocol):
+    """Protocol for wait strategies that determine how long to wait between retries."""
+
+    def __call__(self, retry_state: RetryState) -> float: ...

novastack_utils-1.0.0/novastack_utils/utils.py

@@ -0,0 +1,39 @@
+def validate_enum(el: str, el_name: str, expected_enum) -> str:
+    allowed = {
+        getattr(expected_enum, attr) for attr in vars(expected_enum) if attr.isupper()
+    }
+
+    if el not in allowed:
+        raise ValueError(
+            "Invalid {} '{}'. Input should be: {}.".format(el_name, el, sorted(allowed))
+        )
+
+    return el
+
+
+def validate_type(el, el_name: str, expected_type: type | list[type]):
+    if type(expected_type) is not type and type(expected_type) is not list:
+        raise TypeError(
+            "Invalid expected_type type '{}'. Input should be: ['type', 'list[type]'].".format(
+                expected_type
+            )
+        )
+
+    if type(expected_type) is list:
+        if not any(isinstance(el, t) for t in expected_type):
+            allowed = ", ".join(t.__name__ for t in expected_type)
+            raise TypeError(
+                "Invalid {} type '{}'. Input should be: [{}].".format(
+                    el_name, type(el).__name__, allowed
+                )
+            )
+        return el
+    else:
+        if not isinstance(el, expected_type):  # type: ignore
+            raise TypeError(
+                "Invalid {} type '{}'. Input should be: '{}'.".format(
+                    el_name, type(el).__name__, expected_type.__name__
+                )
+            )
+
+    return el

novastack_utils-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "novastack-utils"
+version = "1.0.0"
+description = "This library contains utilities used across various packages."
+authors = [{ name = "Leonardo Furnielis", email = "leonardofurnielis@outlook.com" }]
+license = { text = "Apache-2.0" }
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "httpx>=0.28.1,<1.0.0",
+    "pydantic>=2.12.5,<3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.3,<10.0.0",
+    "pytest-asyncio>=1.3.0,<2.0.0",
+    "pytest-mock>=3.15.1,<4.0.0",
+    "ruff>=0.15.8,<1.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/novastack-project/novastack/tree/main/novastack-utils"
+
+[tool.hatch.build.targets.sdist]
+include = ["novastack_utils/"]
+
+[tool.hatch.build.targets.wheel]
+include = ["novastack_utils/"]