cloud-bridge-client 0.0.1__py3-none-any.whl

cloud_bridge_client/__init__.py

@@ -0,0 +1,89 @@
+"""
+cloud_bridge_client — Python client library for the Cloud Bridge API.
+
+Quick start::
+
+    from cloud_bridge_client import AwsClient, AWSCredentials
+
+    client = AwsClient(
+        credentials=AWSCredentials(
+            access_key_id="AKIA...",
+            secret_access_key="...",
+            region="eu-central-1",
+            zone="eu-central-1a",
+        ),
+        base_url="http://my-server:8080",
+    )
+
+    client.deploy(config="./cluster.yaml")
+    client.preview(config="./cluster.yaml")
+    client.destroy(
+        cluster_name="my-cluster",
+        stateless_resources=True,
+        config_file=True,
+    )
+"""
+
+__version__ = "0.0.1"
+
+from .auth import AuthManager
+from .client import (
+    DEFAULT_BASE_URL,
+    AwsClient,
+    AzureClient,
+    GcpClient,
+    OpenStackClient,
+)
+from .credentials import (
+    AWSCredentials,
+    AzureCredentials,
+    CloudProviderCredentials,
+    GCPCredentials,
+    OpenStackCredentials,
+    Provider,
+)
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    CloudBridgeClientError,
+    ConfigError,
+    FlavorError,
+    ImageError,
+    NetworkError,
+    ProviderConnectionError,
+    ProviderMismatchError,
+    ProviderNotFoundError,
+    ServerConnectionError,
+    StackOperationError,
+    ValidationError,
+    VolumeError,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AWSCredentials",
+    "ApiError",
+    "AuthManager",
+    "AuthenticationError",
+    "AwsClient",
+    "AzureClient",
+    "AzureCredentials",
+    "CloudBridgeClientError",
+    "CloudProviderCredentials",
+    "ConfigError",
+    "FlavorError",
+    "GCPCredentials",
+    "GcpClient",
+    "ImageError",
+    "NetworkError",
+    "OpenStackClient",
+    "OpenStackCredentials",
+    "Provider",
+    "ProviderConnectionError",
+    "ProviderMismatchError",
+    "ProviderNotFoundError",
+    "ServerConnectionError",
+    "StackOperationError",
+    "ValidationError",
+    "VolumeError",
+]

cloud_bridge_client/auth.py

@@ -0,0 +1,39 @@
+from .credentials import CloudProviderCredentials
+
+
+class AuthManager:
+    """
+    Responsible for building the authentication header from the credential
+    object supplied at client initialisation time.
+
+    The Cloud Bridge API uses a single ``X-API-Key`` header whose value is a
+    colon-separated string encoding the provider type and all necessary
+    credentials::
+
+        aws:ACCESS_KEY_ID:SECRET_ACCESS_KEY:REGION:ZONE
+        gcp:PROJECT:REGION:ZONE:ACCESS_TOKEN
+        openstack:AUTH_URL:APP_CREDS_ID:APP_CREDS_SECRET
+        azure:SUBSCRIPTION_ID:TENANT_ID:CLIENT_ID:CLIENT_SECRET:LOCATION:RG
+
+    Every credential dataclass exposes a ``to_api_key()`` method that returns
+    the correctly formatted string.  AuthManager simply calls that method
+    and wraps the result in the expected header dict.
+    """
+
+    _HEADER_NAME = "X-API-Key"
+
+    def __init__(self, credentials: CloudProviderCredentials) -> None:
+        self._credentials = credentials
+
+    @property
+    def provider(self) -> str:
+        """Return the lowercase provider name ("aws", "gcp", ...)."""
+        return self._credentials.provider.value
+
+    def get_headers(self) -> dict[str, str]:
+        """Return the auth header dict ready to be merged into a request."""
+        return {self._HEADER_NAME: self._credentials.to_api_key()}
+
+    def update_credentials(self, credentials: CloudProviderCredentials) -> None:
+        """Hot-swap credentials without creating a new client instance."""
+        self._credentials = credentials

cloud_bridge_client/client.py

@@ -0,0 +1,422 @@
+"""
+cloud_bridge_client — provider-specific client classes.
+
+Usage::
+
+    from cloud_bridge_client import AwsClient, GcpClient
+    from cloud_bridge_client import AWSCredentials, GCPCredentials
+
+    aws = AwsClient(
+        credentials=AWSCredentials(
+            access_key_id="AKIA...",
+            secret_access_key="...",
+            region="eu-central-1",
+            zone="eu-central-1a",
+        ),
+        base_url="http://my-cloud-bridge-server:8080",
+    )
+
+    aws.deploy(config="./infra/cluster.yaml")
+    aws.preview(config="./infra/cluster.yaml")
+    aws.preview_destroy(cluster_name="my-cluster")
+    aws.destroy(cluster_name="my-cluster", stateless_resources=True, config_file=True)
+    aws.ping()
+"""
+
+from typing import Any, cast
+
+from .auth import AuthManager
+from .credentials import (
+    AWSCredentials,
+    AzureCredentials,
+    GCPCredentials,
+    OpenStackCredentials,
+)
+from .http import ConfigInput, HttpClient
+
+DEFAULT_BASE_URL = "http://localhost:8080"
+
+_PROVIDERS_PATH = "/api/v1/cloud/providers"
+_DEPLOY_PATH = "/api/v1/cloud/stack/deploy"
+_PREVIEW_PATH = "/api/v1/cloud/stack/preview"
+_PREVIEW_DESTROY_PATH = "/api/v1/cloud/stack/preview-destroy"
+_CANCEL_PATH = "/api/v1/cloud/stack/cancel"
+_DESTROY_PATH = "/api/v1/cloud/stack/destroy"
+_VOLUMES_PATH = "/api/v1/cloud/stack/volumes"
+_STATUS_PATH = "/api/v1/cloud/stack/status"
+
+
+class _BaseClient:
+    """
+    Internal base — wires credentials → AuthManager → HttpClient
+    and exposes all cloud operations shared by all providers.
+    """
+
+    def __init__(
+        self,
+        credentials: AWSCredentials | GCPCredentials | AzureCredentials | OpenStackCredentials,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = 600,
+    ) -> None:
+        self._credentials = credentials
+        self._auth = AuthManager(credentials)
+        self._http = HttpClient(base_url=base_url, auth=self._auth, timeout=timeout)
+
+    # ------------------------------------------------------------------
+    # Core operations
+    # ------------------------------------------------------------------
+
+    def deploy(
+        self,
+        config: ConfigInput,
+        *,
+        auto_select: bool = False,
+        request_id: str | None = None,
+    ) -> Any:
+        """
+        Deploy the infrastructure described in *config*.
+
+        Parameters
+        ----------
+        config:
+            Path to a YAML config file (str / pathlib.Path) — must exist
+            on disk. Alternatively, pass raw YAML content as ``bytes``,
+            or a plain ``dict`` that will be serialised to YAML.
+        auto_select:
+            If ``True``, automatically select a flavor when the config
+            does not specify one.
+        request_id:
+            Optional request tracing ID (UUID v4). Generated automatically
+            by the server if absent.
+        """
+        return self._http.post_file(
+            _DEPLOY_PATH,
+            config,
+            auto_select=auto_select,
+            request_id=request_id,
+        )
+
+    def preview(
+        self,
+        config: ConfigInput,
+        *,
+        auto_select: bool = False,
+        request_id: str | None = None,
+    ) -> Any:
+        """
+        Dry-run: show what would change without touching real infrastructure.
+
+        Parameters
+        ----------
+        config:
+            Path to a YAML config file (str / pathlib.Path) — must exist
+            on disk. Alternatively, pass raw YAML content as ``bytes``,
+            or a plain ``dict`` that will be serialised to YAML.
+        auto_select:
+            If ``True``, automatically select a flavor when the config
+            does not specify one.
+        request_id:
+            Optional request tracing ID (UUID v4).
+        """
+        return self._http.post_file(
+            _PREVIEW_PATH,
+            config,
+            auto_select=auto_select,
+            request_id=request_id,
+        )
+
+    def preview_destroy(self, cluster_name: str) -> Any:
+        """Dry-run: list resources that *would* be deleted."""
+        return self._http.post_json(_PREVIEW_DESTROY_PATH, {"cluster_name": cluster_name})
+
+    def cancel(self, cluster_name: str) -> Any:
+        """
+        Cancel an in-progress stack update or clear a stale lock.
+
+        Parameters
+        ----------
+        cluster_name:
+            Name of the cluster whose update should be cancelled.
+        """
+        return self._http.post_json(_CANCEL_PATH, {"cluster_name": cluster_name})
+
+    def destroy(
+        self,
+        cluster_name: str,
+        *,
+        stateless_resources: bool = False,
+        stateful_resources: bool = False,
+        config_file: bool = False,
+        confirm_code: str | None = None,
+        request_id: str | None = None,
+    ) -> Any:
+        """
+        Destroy stack resources. Supports a two-phase confirmation flow.
+
+        **Phase 1** — call with at least one of ``stateless_resources``,
+        ``stateful_resources``, or ``config_file`` set to ``True``.
+        Returns a confirmation response containing a ``code`` that expires.
+
+        **Phase 2** — call again with ``confirm_code`` set to the code from
+        phase 1.  This triggers the actual destruction and returns a job ID.
+
+        Parameters
+        ----------
+        cluster_name:
+            Name of the cluster to destroy.
+        stateless_resources:
+            Delete stateless resources (compute, networks, etc.).
+        stateful_resources:
+            Delete stateful resources (volumes, databases).
+            Requires ``stateless_resources=True``.
+        config_file:
+            Delete the Pulumi config file.
+        confirm_code:
+            Confirmation code from a previous phase-1 call.
+        request_id:
+            Optional request tracing ID (UUID v4).
+
+        Returns
+        -------
+        dict
+            Phase 1: ``{"data": {"warning": str, "code": str, "expire_at": str, "volumes": [...]}}``
+            Phase 2: ``{"data": {"job_id": str, "operation": str, "provider": str, "cluster_name": str}}``
+        """
+        body: dict[str, Any] = {"cluster_name": cluster_name}
+        params: dict[str, Any] = {}
+        if confirm_code is not None:
+            params["confirm_code"] = confirm_code
+        else:
+            params["stateless_resources"] = stateless_resources
+            params["stateful_resources"] = stateful_resources
+            params["config_file"] = config_file
+        return self._http.post_json(_DESTROY_PATH, body, request_id=request_id, params=params)
+
+    # ------------------------------------------------------------------
+    # Info / utility
+    # ------------------------------------------------------------------
+
+    def providers(self) -> list[str]:
+        """
+        Return the list of available cloud provider identifiers.
+
+        Returns
+        -------
+        list[str]
+            e.g. ``["aws", "gcp", "openstack"]``
+        """
+        resp = self._http.get(_PROVIDERS_PATH)
+        return resp.get("data", {}).get("providers", [])
+
+    def volumes(self, cluster_name: str) -> Any:
+        """
+        Return volume fate info for a stack.
+
+        Shows what will happen to each volume when the stack is destroyed.
+
+        Parameters
+        ----------
+        cluster_name:
+            Name of the cluster.
+        """
+        return self._http.get(_VOLUMES_PATH, params={"cluster_name": cluster_name})
+
+    def status(self, cluster_name: str) -> Any:
+        """
+        Return current outputs and last-update summary for the named stack.
+
+        Parameters
+        ----------
+        cluster_name:
+            Name of the cluster.
+        """
+        return self._http.get(_STATUS_PATH, params={"cluster_name": cluster_name})
+
+    def ping(self) -> bool:
+        """Return ``True`` if the Cloud Bridge API server is reachable."""
+        return self._http.ping()
+
+    def update_credentials(
+        self,
+        credentials: AWSCredentials | GCPCredentials | AzureCredentials | OpenStackCredentials,
+    ) -> None:
+        """Hot-swap credentials without creating a new client instance."""
+        self._credentials = credentials
+        self._auth.update_credentials(credentials)
+
+
+# ---------------------------------------------------------------------------
+# Public provider-specific clients
+# ---------------------------------------------------------------------------
+
+
+class AwsClient(_BaseClient):
+    """
+    Cloud Bridge client for **Amazon Web Services**.
+
+    Parameters
+    ----------
+    credentials:
+        :class:`AWSCredentials` instance.
+    base_url:
+        Base URL of the Cloud Bridge API server (default: ``http://localhost:8080``).
+    timeout:
+        Request timeout in seconds (default: 600).
+
+    Example
+    -------
+    ::
+
+        from cloud_bridge_client import AwsClient, AWSCredentials
+
+        client = AwsClient(
+            credentials=AWSCredentials(
+                access_key_id="AKIA...",
+                secret_access_key="...",
+                region="eu-central-1",
+                zone="eu-central-1a",
+            ),
+        )
+        client.deploy(config="cluster.yaml")
+    """
+
+    def __init__(
+        self,
+        credentials: AWSCredentials,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = 600,
+    ) -> None:
+        super().__init__(credentials, base_url, timeout)
+
+    def __repr__(self) -> str:
+        creds = cast(AWSCredentials, self._credentials)
+        return f"AwsClient(region={creds.region!r}, base_url={self._http._base_url!r})"
+
+
+class GcpClient(_BaseClient):
+    """
+    Cloud Bridge client for **Google Cloud Platform**.
+
+    Parameters
+    ----------
+    credentials:
+        :class:`GCPCredentials` instance.
+    base_url:
+        Base URL of the Cloud Bridge API server (default: ``http://localhost:8080``).
+    timeout:
+        Request timeout in seconds (default: 600).
+
+    Example
+    -------
+    ::
+
+        from cloud_bridge_client import GcpClient, GCPCredentials
+
+        client = GcpClient(
+            credentials=GCPCredentials(
+                project="my-project",
+                region="us-central1",
+                zone="us-central1-a",
+                service_account_email="sa@my-project.iam.gserviceaccount.com",
+                private_key="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+            ),
+        )
+        client.deploy(config="cluster.yaml")
+    """
+
+    def __init__(
+        self,
+        credentials: GCPCredentials,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = 600,
+    ) -> None:
+        super().__init__(credentials, base_url, timeout)
+
+    def __repr__(self) -> str:
+        creds = cast(GCPCredentials, self._credentials)
+        return f"GcpClient(project={creds.project!r}, base_url={self._http._base_url!r})"
+
+
+class AzureClient(_BaseClient):
+    """
+    Cloud Bridge client for **Microsoft Azure**.
+
+    Parameters
+    ----------
+    credentials:
+        :class:`AzureCredentials` instance.
+    base_url:
+        Base URL of the Cloud Bridge API server (default: ``http://localhost:8080``).
+    timeout:
+        Request timeout in seconds (default: 600).
+
+    Example
+    -------
+    ::
+
+        from cloud_bridge_client import AzureClient, AzureCredentials
+
+        client = AzureClient(
+            credentials=AzureCredentials(
+                subscription_id="...",
+                tenant_id="...",
+                client_id="...",
+                client_secret="...",
+            ),
+        )
+        client.deploy(config="cluster.yaml")
+    """
+
+    def __init__(
+        self,
+        credentials: AzureCredentials,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = 600,
+    ) -> None:
+        super().__init__(credentials, base_url, timeout)
+
+    def __repr__(self) -> str:
+        creds = cast(AzureCredentials, self._credentials)
+        return f"AzureClient(subscription_id={creds.subscription_id!r}, base_url={self._http._base_url!r})"
+
+
+class OpenStackClient(_BaseClient):
+    """
+    Cloud Bridge client for **OpenStack**.
+
+    Parameters
+    ----------
+    credentials:
+        :class:`OpenStackCredentials` instance.
+    base_url:
+        Base URL of the Cloud Bridge API server (default: ``http://localhost:8080``).
+    timeout:
+        Request timeout in seconds (default: 600).
+
+    Example
+    -------
+    ::
+
+        from cloud_bridge_client import OpenStackClient, OpenStackCredentials
+
+        client = OpenStackClient(
+            credentials=OpenStackCredentials(
+                auth_url="https://my-openstack:5000/v3",
+                application_credential_id="...",
+                application_credential_secret="...",
+            ),
+        )
+        client.deploy(config="cluster.yaml")
+    """
+
+    def __init__(
+        self,
+        credentials: OpenStackCredentials,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = 600,
+    ) -> None:
+        super().__init__(credentials, base_url, timeout)
+
+    def __repr__(self) -> str:
+        creds = cast(OpenStackCredentials, self._credentials)
+        return f"OpenStackClient(auth_url={creds.auth_url!r}, base_url={self._http._base_url!r})"

cloud_bridge_client/credentials.py

@@ -0,0 +1,87 @@
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class Provider(StrEnum):
+    AWS = "aws"
+    GCP = "gcp"
+    AZURE = "azure"
+    OPENSTACK = "openstack"
+
+
+@dataclass
+class AWSCredentials:
+    """Credentials for Amazon Web Services."""
+
+    access_key_id: str
+    secret_access_key: str
+    region: str = "eu-central-1"
+    zone: str = ""
+
+    #: Which provider enum value this maps to (read-only).
+    provider: Provider = field(default=Provider.AWS, init=False, repr=False)
+
+    def to_api_key(self) -> str:
+        """Encode as ``aws:ACCESS_KEY_ID:SECRET_ACCESS_KEY:REGION:ZONE``."""
+        return f"aws:{self.access_key_id}:{self.secret_access_key}:{self.region}:{self.zone}"
+
+
+@dataclass
+class GCPCredentials:
+    """Credentials for Google Cloud Platform."""
+
+    project: str
+    region: str
+    zone: str
+    service_account_email: str
+    private_key: str
+    # access_token: str | None = None
+
+    provider: Provider = field(default=Provider.GCP, init=False, repr=False)
+
+    def to_api_key(self) -> str:
+        """Encode as ``gcp:PROJECT:REGION:ZONE:SERVICE_ACCOUNT:PRIVATE_KEY``."""
+        key_for_header = self.private_key.replace("\n", "\\n")
+        return f"gcp:{self.project}:{self.region}:{self.zone}:{self.service_account_email}:{key_for_header}"
+
+
+@dataclass
+class OpenStackCredentials:
+    """Credentials for OpenStack."""
+
+    auth_url: str
+    application_credential_id: str
+    application_credential_secret: str
+    region_name: str = "RegionOne"
+
+    provider: Provider = field(default=Provider.OPENSTACK, init=False, repr=False)
+
+    def to_api_key(self) -> str:
+        """Encode as ``openstack:AUTH_URL:APP_CREDS_ID:APP_CREDS_SECRET``."""
+        return f"openstack:{self.auth_url}:{self.application_credential_id}:{self.application_credential_secret}"
+
+
+@dataclass
+class AzureCredentials:
+    """Credentials for Microsoft Azure."""
+
+    subscription_id: str
+    tenant_id: str
+    client_id: str
+    client_secret: str
+    location: str = "east's"
+    resource_group: str = "universal-infra-rg"
+
+    provider: Provider = field(default=Provider.AZURE, init=False, repr=False)
+
+    def to_api_key(self) -> str:
+        """Encode as ``azure:SUB:TENANT:CLIENT_ID:CLIENT_SECRET:LOCATION:RG``."""
+        return (
+            f"azure:{self.subscription_id}:{self.tenant_id}:"
+            f"{self.client_id}:{self.client_secret}:"
+            f"{self.location}:{self.resource_group}"
+        )
+
+
+# Convenience union type used throughout the library.
+CloudProviderCredentials = AWSCredentials | GCPCredentials | AzureCredentials | OpenStackCredentials