forktex-cloud 0.2.3__py3-none-any.whl

forktex_cloud/client/client.py

@@ -0,0 +1,599 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of forktex-cloud.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Typed httpx client for the ForkTex Cloud control plane API.
+
+All methods are synchronous — the CLI is sync (click-based).
+Supports dual auth: JWT Bearer token (user login) or X-API-Key (org-scoped CI/CD).
+"""
+
+from __future__ import annotations
+
+import base64
+import fnmatch
+import io
+import json
+import tarfile
+from pathlib import Path
+from typing import Any, Callable, Iterator
+
+import httpx
+
+from forktex_cloud.client.generated import (
+    ApiKeyCreated,
+    ApiKeyRead,
+    EnvironmentRead,
+    EventRead,
+    HealthRead,
+    JobResponse,
+    MeResponse,
+    OpsResponse,
+    OrgRead,
+    ProjectRead,
+    ServerRead,
+    StatusResponse,
+    TokenResponse,
+    VaultGetResponse,
+    WorkspaceRead,
+)
+from forktex_cloud.config import CloudContext
+
+
+class CloudAPIError(Exception):
+    """Raised when the cloud API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class ForktexCloudClient:
+    """Synchronous client for the ForkTex Cloud API.
+
+    Supports dual auth:
+    - ``access_token``: JWT Bearer token (preferred, from ``forktex cloud login``)
+    - ``account_key``: Org-scoped API key (for CI/CD pipelines)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        account_key: str | None = None,
+        *,
+        access_token: str | None = None,
+        org_id: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._account_key = account_key
+        self._access_token = access_token
+        self._org_id = org_id
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if access_token:
+            headers["Authorization"] = f"Bearer {access_token}"
+        elif account_key:
+            headers["X-API-Key"] = account_key
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    @classmethod
+    def from_context(cls, ctx: CloudContext, **kwargs) -> ForktexCloudClient:
+        """Create a client from a CloudContext."""
+        ctx.require_connection()
+        return cls(
+            ctx.controller,  # type: ignore[arg-type]
+            ctx.account_key,
+            access_token=ctx.access_token,
+            org_id=ctx.org_id,
+            **kwargs,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    # ── helpers ──
+
+    @property
+    def _org_prefix(self) -> str:
+        """URL prefix for org-scoped routes: /api/org/{org_id}."""
+        if not self._org_id:
+            raise RuntimeError("No org_id configured. Run: forktex cloud login")
+        return f"/api/org/{self._org_id}"
+
+    def _check(self, resp: httpx.Response) -> httpx.Response:
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                detail = body.get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise CloudAPIError(resp.status_code, str(detail))
+        return resp
+
+    # ── Auth (public, no org prefix) ──
+
+    def register(self, email: str, password: str) -> TokenResponse:
+        resp = self._check(
+            self._client.post("/api/auth/register", json={"email": email, "password": password})
+        )
+        return TokenResponse.model_validate(resp.json())
+
+    def login(self, email: str, password: str) -> TokenResponse:
+        resp = self._check(
+            self._client.post("/api/auth/login", json={"email": email, "password": password})
+        )
+        return TokenResponse.model_validate(resp.json())
+
+    def me(self) -> MeResponse:
+        resp = self._check(self._client.get("/api/me"))
+        return MeResponse.model_validate(resp.json())
+
+    # ── Orgs (JWT-authed, no org prefix) ──
+
+    def list_orgs(self) -> list[OrgRead]:
+        resp = self._check(self._client.get("/api/orgs"))
+        return [OrgRead.model_validate(o) for o in resp.json()]
+
+    # ── Health (public, no org prefix) ──
+
+    def health(self) -> HealthRead:
+        resp = self._check(self._client.get("/api/health"))
+        return HealthRead.model_validate(resp.json())
+
+    # ── Projects (org-scoped) ──
+
+    def list_projects(self) -> list[ProjectRead]:
+        resp = self._check(self._client.get(f"{self._org_prefix}/projects"))
+        return [ProjectRead.model_validate(p) for p in resp.json()]
+
+    def create_project(
+        self,
+        name: str,
+        *,
+        manifest: str | None = None,
+        project_id: str | None = None,
+    ) -> ProjectRead:
+        body: dict[str, Any] = {"name": name}
+        if manifest is not None:
+            body["manifest"] = manifest
+        if project_id is not None:
+            body["project_id"] = project_id
+        resp = self._check(self._client.post(f"{self._org_prefix}/projects", json=body))
+        return ProjectRead.model_validate(resp.json())
+
+    def get_project(self, project_id: str) -> ProjectRead:
+        resp = self._check(self._client.get(f"{self._org_prefix}/projects/{project_id}"))
+        return ProjectRead.model_validate(resp.json())
+
+    def list_project_environments(self, project_id: str) -> list[EnvironmentRead]:
+        resp = self._check(
+            self._client.get(f"{self._org_prefix}/projects/{project_id}/environments")
+        )
+        return [EnvironmentRead.model_validate(e) for e in resp.json()]
+
+    # ── Servers (org-scoped) ──
+
+    def list_servers(self) -> list[ServerRead]:
+        resp = self._check(self._client.get(f"{self._org_prefix}/servers"))
+        return [ServerRead.model_validate(s) for s in resp.json()]
+
+    def create_server(
+        self,
+        name: str,
+        *,
+        flavour: str | None = None,
+        region: str | None = None,
+        server_type: str | None = None,
+        image: str | None = None,
+        location: str | None = None,
+        project_id: str = "",
+        environment: str | None = None,
+    ) -> ServerRead:
+        body: dict[str, Any] = {"name": name, "project_id": project_id}
+        if flavour is not None:
+            body["flavour"] = flavour
+        if region is not None:
+            body["region"] = region
+        if server_type is not None:
+            body["server_type"] = server_type
+        if image is not None:
+            body["image"] = image
+        if location is not None:
+            body["location"] = location
+        if environment is not None:
+            body["environment"] = environment
+        resp = self._check(self._client.post(f"{self._org_prefix}/servers", json=body))
+        return ServerRead.model_validate(resp.json())
+
+    def get_server(self, server_id: str) -> ServerRead:
+        resp = self._check(self._client.get(f"{self._org_prefix}/servers/{server_id}"))
+        return ServerRead.model_validate(resp.json())
+
+    def destroy_server(self, server_id: str) -> StatusResponse:
+        resp = self._check(self._client.delete(f"{self._org_prefix}/servers/{server_id}"))
+        return StatusResponse.model_validate(resp.json())
+
+    def import_server(
+        self,
+        name: str,
+        host: str,
+        *,
+        user: str = "root",
+        project_id: str | None = None,
+    ) -> StatusResponse:
+        body: dict[str, Any] = {"name": name, "host": host, "user": user}
+        if project_id is not None:
+            body["project_id"] = project_id
+        resp = self._check(self._client.post(f"{self._org_prefix}/servers/import", json=body))
+        return StatusResponse.model_validate(resp.json())
+
+    def server_status(self, server_id: str) -> dict[str, Any]:
+        resp = self._check(self._client.get(f"{self._org_prefix}/servers/{server_id}/status"))
+        return resp.json()
+
+    def server_restart(self, server_id: str, *, service: str | None = None) -> OpsResponse:
+        body: dict[str, Any] = {}
+        if service is not None:
+            body["service"] = service
+        resp = self._check(
+            self._client.post(f"{self._org_prefix}/servers/{server_id}/restart", json=body)
+        )
+        return OpsResponse.model_validate(resp.json())
+
+    def server_exec(self, server_id: str, *, service: str, command: str) -> OpsResponse:
+        body = {"service": service, "command": command}
+        resp = self._check(
+            self._client.post(f"{self._org_prefix}/servers/{server_id}/exec", json=body)
+        )
+        return OpsResponse.model_validate(resp.json())
+
+    def server_switch(self, server_id: str, *, component: str, to_color: str) -> OpsResponse:
+        body = {"component": component, "to_color": to_color}
+        resp = self._check(
+            self._client.post(f"{self._org_prefix}/servers/{server_id}/switch", json=body)
+        )
+        return OpsResponse.model_validate(resp.json())
+
+    def server_update(self, server_id: str, *, component: str, new_image: str) -> OpsResponse:
+        body = {"component": component, "new_image": new_image}
+        resp = self._check(
+            self._client.post(f"{self._org_prefix}/servers/{server_id}/update", json=body)
+        )
+        return OpsResponse.model_validate(resp.json())
+
+    def stream_logs(
+        self,
+        server_id: str,
+        *,
+        service: str | None = None,
+        lines: int = 50,
+        since: str | None = None,
+        query: str | None = None,
+    ) -> Iterator[str]:
+        """Stream server logs via SSE. Yields raw SSE lines.
+
+        When the server has Loki enabled and ``since`` or ``query`` are
+        provided, the API queries Loki's LogQL instead of ``docker logs``.
+        """
+        params: dict[str, Any] = {"lines": lines}
+        if service:
+            params["service"] = service
+        if since:
+            params["since"] = since
+        if query:
+            params["query"] = query
+        with self._client.stream(
+            "GET",
+            f"{self._org_prefix}/servers/{server_id}/logs",
+            params=params,
+        ) as resp:
+            self._check(resp)
+            for line in resp.iter_lines():
+                yield line
+
+    # ── Deploy (org-scoped) ──
+
+    def deploy(
+        self,
+        server_id: str,
+        *,
+        tags: list[str] | None = None,
+        service: str | None = None,
+        manifest_data: dict | None = None,
+        assets_tarball_b64: str | None = None,
+        project_dir: Path | None = None,
+    ) -> JobResponse:
+        body: dict[str, Any] = {"server_id": server_id}
+        if tags is not None:
+            body["tags"] = tags
+        if service is not None:
+            body["service"] = service
+
+        # Load local manifest if project_dir is provided
+        if project_dir and not manifest_data:
+            manifest_path = project_dir / "forktex.json"
+            if manifest_path.exists():
+                manifest_data = json.loads(manifest_path.read_text())
+
+        if manifest_data is not None:
+            body["manifest_data"] = manifest_data
+
+        # Auto-detect and tarball local asset directories from volumes
+        if project_dir and manifest_data and not assets_tarball_b64:
+            tarball = self._build_assets_tarball(project_dir, manifest_data)
+            if tarball:
+                body["assets_tarball_b64"] = tarball
+        elif assets_tarball_b64 is not None:
+            body["assets_tarball_b64"] = assets_tarball_b64
+
+        resp = self._check(self._client.post(f"{self._org_prefix}/deploy", json=body))
+        return JobResponse.model_validate(resp.json())
+
+    # ── Pipeline: up / down (org-scoped) ──
+
+    def up(
+        self,
+        *,
+        name: str | None = None,
+        flavour: str | None = None,
+        region: str | None = None,
+        env: str | None = None,
+        skip_dns: bool = False,
+        skip_ssl: bool = False,
+        manifest_data: dict | None = None,
+        project_dir: Path | None = None,
+    ) -> JobResponse:
+        """Trigger the up pipeline via POST {org_prefix}/up.
+
+        If *project_dir* is provided the local ``forktex.json`` is read and sent
+        as ``manifest_data``.  Local asset directories referenced as bind-mount
+        volumes are auto-tarballed and sent as ``assets_tarball_b64``.
+        """
+        body: dict[str, Any] = {
+            "skip_dns": skip_dns,
+            "skip_ssl": skip_ssl,
+        }
+        if name:
+            body["name"] = name
+        if flavour:
+            body["flavour"] = flavour
+        if region:
+            body["region"] = region
+        if env:
+            body["env"] = env
+
+        # Load local manifest if project_dir is provided
+        if project_dir and not manifest_data:
+            manifest_path = project_dir / "forktex.json"
+            if manifest_path.exists():
+                manifest_data = json.loads(manifest_path.read_text())
+
+        if manifest_data:
+            body["manifest_data"] = manifest_data
+
+        # Auto-detect and tarball local asset directories from volumes
+        if project_dir and manifest_data:
+            tarball = self._build_assets_tarball(project_dir, manifest_data)
+            if tarball:
+                body["assets_tarball_b64"] = tarball
+
+        resp = self._check(self._client.post(f"{self._org_prefix}/up", json=body))
+        return JobResponse.model_validate(resp.json())
+
+    def down(
+        self,
+        *,
+        keep_dns: bool = False,
+        name: str | None = None,
+        manifest_data: dict | None = None,
+        project_dir: Path | None = None,
+    ) -> JobResponse:
+        """Trigger the down pipeline via POST {org_prefix}/down."""
+        body: dict[str, Any] = {"keep_dns": keep_dns}
+        if name:
+            body["name"] = name
+
+        # Load local manifest if project_dir is provided
+        if project_dir and not manifest_data:
+            manifest_path = project_dir / "forktex.json"
+            if manifest_path.exists():
+                manifest_data = json.loads(manifest_path.read_text())
+
+        if manifest_data:
+            body["manifest_data"] = manifest_data
+
+        resp = self._check(self._client.post(f"{self._org_prefix}/down", json=body))
+        return JobResponse.model_validate(resp.json())
+
+    @staticmethod
+    def _dockerignore_filter(
+        directory: Path,
+    ) -> Callable[[tarfile.TarInfo], tarfile.TarInfo | None] | None:
+        """Parse a .dockerignore file and return a tarfile filter.
+
+        Returns ``None`` if no ``.dockerignore`` exists in *directory*.
+        The returned filter accepts a ``TarInfo`` and returns ``None``
+        for entries that should be excluded.
+        """
+        ignore_file = directory / ".dockerignore"
+        if not ignore_file.is_file():
+            return None
+
+        patterns: list[str] = []
+        for line in ignore_file.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            patterns.append(line)
+
+        if not patterns:
+            return None
+
+        def _filter(info: tarfile.TarInfo) -> tarfile.TarInfo | None:
+            # info.name is the arcname (e.g. "client/build/node_modules/...")
+            # We need to check path components against patterns
+            parts = Path(info.name).parts
+            for part in parts:
+                for pat in patterns:
+                    if fnmatch.fnmatch(part, pat):
+                        return None
+            return info
+
+        return _filter
+
+    @staticmethod
+    def _build_assets_tarball(project_dir: Path, manifest_data: dict) -> str | None:
+        """Scan manifest services for bind-mount volumes and build contexts, tarball them."""
+        # (local_path, arcname_prefix, source_basename)
+        local_entries: list[tuple[Path, str, str]] = []
+        for svc in manifest_data.get("services", []):
+            svc_id = svc.get("id", "")
+            svc_type = svc.get("type", "compute")
+            service_prefix = f"services/{svc_id}"
+
+            # Volume-mounted local files and directories
+            for vol in svc.get("volumes", []):
+                if isinstance(vol, str) and ":" in vol:
+                    parts = vol.split(":")
+                    local_part = parts[0]
+                    if local_part.startswith("./") or local_part.startswith("/"):
+                        local_path = (project_dir / local_part).resolve()
+                        if local_path.is_dir() or local_path.is_file():
+                            source_basename = Path(local_part).name
+                            local_entries.append((local_path, service_prefix, source_basename))
+
+            # Build context: if image has no registry prefix and a matching
+            # directory with a Dockerfile exists, include it
+            if svc_type != "persistence":
+                image = svc.get("image", "")
+                if "/" not in image:
+                    build_dir = project_dir / svc_id
+                    if (build_dir / "Dockerfile").is_file():
+                        local_entries.append((build_dir, f"artifacts/{svc_id}", "build"))
+
+        if not local_entries:
+            return None
+
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+            for local_path, prefix, source_basename in local_entries:
+                arcname = f"{prefix}/{source_basename}"
+                if local_path.is_file():
+                    tar.add(str(local_path), arcname=arcname)
+                else:
+                    tar_filter = ForktexCloudClient._dockerignore_filter(local_path)
+                    tar.add(str(local_path), arcname=arcname, filter=tar_filter)
+
+        return base64.b64encode(buf.getvalue()).decode("ascii")
+
+    # ── Validate (org-scoped) ──
+
+    def validate(self, *, manifest_path: str | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if manifest_path is not None:
+            body["manifest_path"] = manifest_path
+        resp = self._check(self._client.post(f"{self._org_prefix}/validate", json=body or None))
+        return resp.json()
+
+    # ── Manifest (org-scoped) ──
+
+    def get_manifest(self, *, env: str | None = None) -> dict[str, Any]:
+        params: dict[str, str] = {}
+        if env:
+            params["env"] = env
+        resp = self._check(self._client.get(f"{self._org_prefix}/manifest", params=params))
+        return resp.json()
+
+    # ── Vault (org-scoped) ──
+
+    def vault_list(self, *, env: str = "default") -> list[str]:
+        resp = self._check(self._client.get(f"{self._org_prefix}/vault", params={"env": env}))
+        return resp.json()
+
+    def vault_get(self, key: str, *, env: str = "default") -> VaultGetResponse:
+        resp = self._check(self._client.get(f"{self._org_prefix}/vault/{key}", params={"env": env}))
+        return VaultGetResponse.model_validate(resp.json())
+
+    def vault_set(self, key: str, value: str, *, env: str = "default") -> StatusResponse:
+        body = {"key": key, "value": value, "env": env}
+        resp = self._check(self._client.post(f"{self._org_prefix}/vault", json=body))
+        return StatusResponse.model_validate(resp.json())
+
+    def vault_delete(self, key: str, *, env: str = "default") -> StatusResponse:
+        resp = self._check(
+            self._client.delete(f"{self._org_prefix}/vault/{key}", params={"env": env})
+        )
+        return StatusResponse.model_validate(resp.json())
+
+    # ── Events (org-scoped) ──
+
+    def list_events(self, *, project_id: str | None = None) -> list[EventRead]:
+        params: dict[str, str] = {}
+        if project_id:
+            params["project_id"] = project_id
+        resp = self._check(self._client.get(f"{self._org_prefix}/events", params=params))
+        return [EventRead.model_validate(e) for e in resp.json()]
+
+    # ── Workspace (org-scoped) ──
+
+    def get_workspace(self) -> WorkspaceRead:
+        resp = self._check(self._client.get(f"{self._org_prefix}/workspace"))
+        return WorkspaceRead.model_validate(resp.json())
+
+    def update_workspace(
+        self,
+        *,
+        current_environment: str | None = None,
+        current_server: str | None = None,
+    ) -> StatusResponse:
+        body: dict[str, Any] = {}
+        if current_environment is not None:
+            body["current_environment"] = current_environment
+        if current_server is not None:
+            body["current_server"] = current_server
+        resp = self._check(self._client.patch(f"{self._org_prefix}/workspace", json=body))
+        return StatusResponse.model_validate(resp.json())
+
+    # ── API Keys (org-scoped) ──
+
+    def create_api_key(self, label: str) -> ApiKeyCreated:
+        resp = self._check(self._client.post(f"{self._org_prefix}/api-keys", json={"label": label}))
+        return ApiKeyCreated.model_validate(resp.json())
+
+    def list_api_keys(self) -> list[ApiKeyRead]:
+        resp = self._check(self._client.get(f"{self._org_prefix}/api-keys"))
+        return [ApiKeyRead.model_validate(k) for k in resp.json()]
+
+    def delete_api_key(self, key_id: str) -> StatusResponse:
+        resp = self._check(self._client.delete(f"{self._org_prefix}/api-keys/{key_id}"))
+        return StatusResponse.model_validate(resp.json())