forktex-cloud 0.2.3__py3-none-any.whl

forktex_cloud/config.py

@@ -0,0 +1,63 @@
+# 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/>.
+
+"""Cloud context model.
+
+Pure data model — no filesystem I/O.  The host application (e.g. forktex-py)
+is responsible for discovering, loading, and persisting cloud context.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class CloudContext(BaseModel):
+    """Resolved cloud CLI state."""
+
+    controller: Optional[str] = None
+    account_key: Optional[str] = None
+    access_token: Optional[str] = None
+    org_id: Optional[str] = None
+    region: Optional[str] = None
+    project_keys: dict[str, str] = Field(default_factory=dict)
+    current_project: Optional[str] = None
+    current_server: Optional[str] = None
+    current_environment: Optional[str] = None
+
+    @property
+    def is_connected(self) -> bool:
+        """True if a controller URL and some auth credential are configured."""
+        return bool(self.controller and (self.access_token or self.account_key))
+
+    def require_connection(self) -> None:
+        """Raise if not connected to a cloud controller."""
+        if not self.controller:
+            raise RuntimeError("No cloud controller configured. Run: forktex cloud login")
+        if not self.access_token and not self.account_key:
+            raise RuntimeError("No credentials configured. Run: forktex cloud login")
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump()

forktex_cloud/manifest/__init__.py

@@ -0,0 +1,58 @@
+# 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/>.
+
+"""Manifest loading, env-overlay merging, and typed validation.
+
+The ``Manifest`` class is the public entry point for loading
+``forktex.json``. Construction validates the ``cloud:`` block eagerly via
+``parse_cloud_block`` against the canonical Pydantic schemas in
+``forktex_cloud.manifest.schema`` (which import from the OpenAPI-codegenned
+``forktex_cloud.client.generated`` module).
+
+Validation happens at construction — there is no separate ``validate()``
+function any more. Catch ``ManifestError`` to handle invalid manifests.
+"""
+
+from forktex_cloud.manifest.errors import ManifestError
+from forktex_cloud.manifest.loader import Manifest
+from forktex_cloud.manifest.merge import deep_merge
+from forktex_cloud.manifest.schema import (
+    CloudManifest,
+    NativeBuild,
+    ProjectDeployment,
+    SingleContainer,
+    StaticSite,
+    parse_cloud_block,
+)
+
+__all__ = [
+    "Manifest",
+    "ManifestError",
+    "deep_merge",
+    "parse_cloud_block",
+    "CloudManifest",
+    "ProjectDeployment",
+    "StaticSite",
+    "SingleContainer",
+    "NativeBuild",
+]

forktex_cloud/manifest/errors.py

@@ -0,0 +1,34 @@
+# 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/>.
+
+"""Single exception type for manifest validation errors."""
+
+from __future__ import annotations
+
+
+class ManifestError(Exception):
+    """Raised when a manifest fails to parse or validate.
+
+    Wraps Pydantic ``ValidationError`` so call sites only need to catch
+    one exception type.
+    """

forktex_cloud/manifest/loader.py

@@ -0,0 +1,296 @@
+# 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/>.
+
+"""Manifest loading, env-overlay merging, and dict-shaped accessors.
+
+This module is the SDK's public manifest API. Internally it validates the
+``cloud:`` block against the canonical Pydantic schemas in
+``forktex_cloud.manifest.schema`` (which delegates to the OpenAPI-codegenned
+models at ``forktex_cloud.client.generated``).
+
+Public surface preserved for backward compatibility:
+
+- ``Manifest.load(path, env=...)`` — read JSON, apply env overlay, validate.
+- ``Manifest.from_dict(data, env=...)`` — same but from an in-memory dict.
+- All ``@property`` accessors (``services``, ``infrastructure``, ``gateway``,
+  ``gateway_ssl_enabled``, ``primary_domain``, …) return the same dict /
+  string / bool shapes they always have.
+- ``Manifest.cloud`` — NEW: the typed Pydantic model, for new call sites
+  that want typed attribute access.
+
+``ManifestError`` is raised eagerly during ``Manifest.__init__`` if the
+``cloud:`` block fails validation.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from forktex_cloud.manifest.errors import ManifestError
+from forktex_cloud.manifest.merge import deep_merge
+from forktex_cloud.manifest.schema import CloudManifest, parse_cloud_block
+
+__all__ = ["Manifest", "ManifestError"]
+
+
+def _merge_services(
+    base_services: list[dict[str, Any]],
+    overlay_services: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Merge service lists by matching ``id``.
+
+    Overlay entries whose ``id`` matches a base entry are shallow-merged
+    onto that entry (overlay wins).  Overlay entries with no match are
+    appended.  Base entries with no overlay counterpart are kept as-is.
+    """
+    seen: set[str] = set()
+    merged: list[dict[str, Any]] = []
+    for bc in base_services:
+        cid = bc["id"]
+        copy = dict(bc)
+        overlay_match = next((oc for oc in overlay_services if oc.get("id") == cid), None)
+        if overlay_match is not None:
+            copy.update(overlay_match)
+            seen.add(cid)
+        merged.append(copy)
+    for oc in overlay_services:
+        if oc.get("id") not in seen:
+            merged.append(dict(oc))
+    return merged
+
+
+class Manifest:
+    """Loaded forktex.json wrapper.
+
+    Eagerly validates the ``cloud:`` block at construction. Exposes the
+    raw dict via accessor methods for compatibility with existing call
+    sites, AND the typed model via ``self.cloud`` for new code.
+    """
+
+    def __init__(
+        self,
+        data: dict[str, Any],
+        path: Path,
+        *,
+        env_name: str | None = None,
+    ) -> None:
+        self.data = data
+        self.path = path
+        self.env_name = env_name
+        # Eager validation — raises ManifestError on bad input.
+        self.cloud: CloudManifest = parse_cloud_block(self.root)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], *, env: str | None = None) -> "Manifest":
+        """Build a Manifest from an in-memory dict (no file needed)."""
+        return cls(data, path=Path("/dev/null"), env_name=env)
+
+    @classmethod
+    def load(cls, path: Path, *, env: str | None = None) -> "Manifest":
+        if not path.is_file():
+            raise ManifestError(f"Manifest not found: {path}")
+        with open(path) as f:
+            data = json.load(f)
+
+        if env:
+            overlay_path = path.parent / f"forktex.{env}.json"
+            if overlay_path.is_file():
+                with open(overlay_path) as f:
+                    overlay = json.load(f)
+                base_root = data.get("cloud", data)
+                overlay_root = overlay.get("cloud", overlay)
+                if "services" in overlay_root and "services" in base_root:
+                    overlay = dict(overlay)
+                    if "cloud" in overlay:
+                        overlay["cloud"] = dict(overlay["cloud"])
+                        overlay["cloud"]["services"] = _merge_services(
+                            base_root["services"], overlay_root["services"]
+                        )
+                    else:
+                        overlay["services"] = _merge_services(
+                            base_root["services"], overlay_root["services"]
+                        )
+                data = deep_merge(data, overlay)
+
+        return cls(data, path, env_name=env)
+
+    # ── shape adapters ──
+
+    @property
+    def root(self) -> dict[str, Any]:
+        """Transparent unwrapper for both flat and ``cloud:``-nested shapes."""
+        return self.data.get("cloud", self.data)
+
+    # ── identity / metadata ──
+
+    @property
+    def api_version(self) -> str:
+        return self.root.get("apiVersion", "")
+
+    @property
+    def kind(self) -> str:
+        return self.root.get("kind", "")
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        return self.root.get("metadata", {})
+
+    @property
+    def name(self) -> str:
+        return self.metadata.get("name", "")
+
+    @property
+    def project_id(self) -> str:
+        return self.metadata.get("projectId", "")
+
+    # ── deployment ──
+
+    @property
+    def deployment(self) -> dict[str, Any]:
+        return self.root.get("deployment", {})
+
+    @property
+    def strategy(self) -> str:
+        return self.deployment.get("strategy", "blue-green")
+
+    @property
+    def retries(self) -> int:
+        return int(self.deployment.get("healthRetries", 30))
+
+    @property
+    def drain_delay(self) -> int:
+        return int(self.deployment.get("drainDelaySeconds", 5))
+
+    @property
+    def graceful_wait(self) -> int:
+        return int(self.deployment.get("gracefulStopSeconds", 30))
+
+    # ── infrastructure ──
+
+    @property
+    def infrastructure(self) -> dict[str, Any]:
+        return self.root.get("infrastructure", {})
+
+    @property
+    def infra_provider(self) -> str:
+        return self.infrastructure.get("provider", "hetzner")
+
+    @property
+    def infra_flavour(self) -> str:
+        return self.infrastructure.get("flavour", "starter")
+
+    @property
+    def infra_region(self) -> str:
+        return self.infrastructure.get("region", "eu-central")
+
+    @property
+    def infra_image(self) -> str:
+        return self.infrastructure.get("image", "ubuntu-24.04")
+
+    # ── services ──
+
+    @property
+    def services(self) -> list[dict[str, Any]]:
+        return self.root.get("services", [])
+
+    def service_by_id(self, sid: str) -> dict[str, Any] | None:
+        return next((s for s in self.services if s["id"] == sid), None)
+
+    def service_ids(self) -> list[str]:
+        return [s["id"] for s in self.services]
+
+    def compute_services(self) -> list[dict[str, Any]]:
+        return [s for s in self.services if s.get("type") == "compute"]
+
+    def persistence_services(self) -> list[dict[str, Any]]:
+        return [s for s in self.services if s.get("type") == "persistence"]
+
+    def observability_services(self) -> list[dict[str, Any]]:
+        return [s for s in self.services if s.get("type") == "observability"]
+
+    def services_for_env(self, env: str | None = None) -> list[dict[str, Any]]:
+        """Filter services by ``environments`` list; services without the field run in every env."""
+        result = []
+        for s in self.services:
+            envs = s.get("environments")
+            if envs is not None and env not in envs:
+                continue
+            result.append(s)
+        return result
+
+    # ── observability ──
+
+    @property
+    def observability(self) -> dict[str, Any]:
+        return self.root.get("observability", {})
+
+    @property
+    def observability_enabled(self) -> bool:
+        return self.observability.get("enabled", False)
+
+    # ── gateway ──
+
+    @property
+    def gateway(self) -> dict[str, Any]:
+        return self.root.get("gateway", {})
+
+    @property
+    def gateway_domains(self) -> list[dict[str, Any]]:
+        return self.gateway.get("domains", [])
+
+    @property
+    def gateway_ssl(self) -> dict[str, Any]:
+        return self.gateway.get("ssl", {})
+
+    @property
+    def gateway_ssl_enabled(self) -> bool:
+        if not self.gateway:
+            return False
+        return self.gateway_ssl.get("enabled", True)
+
+    @property
+    def gateway_ssl_provider(self) -> str:
+        return self.gateway_ssl.get("provider", "letsencrypt")
+
+    @property
+    def ssl_challenge(self) -> str:
+        return self.gateway_ssl.get("challenge", "dns-01")
+
+    @property
+    def ssl_dns_provider(self) -> str:
+        return self.gateway_ssl.get("dnsProvider", "cloudflare")
+
+    @property
+    def primary_domain(self) -> str | None:
+        domains = self.gateway_domains
+        return domains[0]["host"] if domains else None
+
+    # ── persistence ──
+
+    def save(self, path: Path | None = None) -> None:
+        target = path or self.path
+        with open(target, "w") as f:
+            json.dump(self.data, f, indent=2)
+            f.write("\n")

forktex_cloud/manifest/merge.py

@@ -0,0 +1,52 @@
+# 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/>.
+
+"""Deep merge utility for manifest overlays."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def deep_merge(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *overlay* onto *base*, returning a new dict.
+
+    - Nested dicts merge recursively (overlay wins on conflict).
+    - Arrays replace entirely (no element-level merge).
+    - Scalars from overlay overwrite base.
+    - Neither input dict is mutated.
+    """
+    result: dict[str, Any] = {}
+    all_keys = set(base) | set(overlay)
+    for key in all_keys:
+        if key in overlay and key in base:
+            b_val, o_val = base[key], overlay[key]
+            if isinstance(b_val, dict) and isinstance(o_val, dict):
+                result[key] = deep_merge(b_val, o_val)
+            else:
+                result[key] = o_val
+        elif key in overlay:
+            result[key] = overlay[key]
+        else:
+            result[key] = base[key]
+    return result

forktex_cloud/manifest/schema.py

@@ -0,0 +1,88 @@
+# 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/>.
+
+"""Discriminated union over the generated cloud manifest kinds.
+
+The OpenAPI codegen at ``forktex_cloud.client.generated`` emits each kind
+(``ProjectDeployment``, ``StaticSite``, ``SingleContainer``, ``NativeBuild``)
+as an independent ``BaseModel``, but does not emit a top-level union since
+that union only exists in OpenAPI as part of nested request bodies
+(``UpRequest.manifest_data``). We assemble it here so the manifest layer can
+validate raw dicts against the canonical schema in one shot.
+
+Adding a new kind: import it from ``forktex_cloud.client.generated`` and
+append it to the ``CloudManifest`` union below. No other change is needed
+here as long as the new kind has a unique ``kind`` literal.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import Field, TypeAdapter, ValidationError
+
+from forktex_cloud.client.generated import (
+    NativeBuild,
+)
+from forktex_cloud.client.generated import (
+    ProjectDeploymentInput as ProjectDeployment,
+)
+from forktex_cloud.client.generated import (
+    SingleContainerInput as SingleContainer,
+)
+from forktex_cloud.client.generated import (
+    StaticSiteInput as StaticSite,
+)
+from forktex_cloud.manifest.errors import ManifestError
+
+CloudManifest = Annotated[
+    ProjectDeployment | StaticSite | SingleContainer | NativeBuild,
+    Field(discriminator="kind"),
+]
+
+_adapter: TypeAdapter[CloudManifest] = TypeAdapter(CloudManifest)
+
+
+def parse_cloud_block(raw: dict[str, Any]) -> CloudManifest:
+    """Validate the raw ``cloud:`` block and return the typed model.
+
+    Accepts either a top-level forktex.json dict (with a ``cloud:`` key) or
+    a flat cloud-only dict — auto-detects shape.
+    """
+    if not isinstance(raw, dict):
+        raise ManifestError(f"cloud block must be a dict, got {type(raw).__name__}")
+    block = raw.get("cloud", raw)
+    try:
+        return _adapter.validate_python(block)
+    except ValidationError as exc:
+        raise ManifestError(str(exc)) from exc
+
+
+__all__ = [
+    "CloudManifest",
+    "parse_cloud_block",
+    "ProjectDeployment",
+    "StaticSite",
+    "SingleContainer",
+    "NativeBuild",
+]