forktex-cloud 0.5.0__tar.gz → 2.0.0__tar.gz

{forktex_cloud-0.5.0 → forktex_cloud-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forktex-cloud
-Version: 0.5.0
+Version: 2.0.0
 Summary: Typed Python SDK for the ForkTex Cloud platform — provision, deploy, and manage VPS-backed apps via a declarative manifest.
 License-Expression: MIT
 License-File: LICENSE
@@ -153,7 +153,7 @@ client.vault_delete("POSTGRES_PASSWORD")
 | Module | Purpose |
 |---|---|
 | `forktex_cloud.client` | Typed sync httpx client (`Cloud`) + all OpenAPI-codegenned Pydantic models (`ServerRead`, `ProjectRead`, `EventRead`, `VaultGetResponse`, ...) |
-| `forktex_cloud.manifest` | `Manifest` loader, discriminated-union schema (v1beta2), deep-merge for env overlays, `ManifestError` |
+| `forktex_cloud.manifest` | `Manifest` loader, discriminated-union schema (v1), deep-merge for env overlays, `ManifestError` |
 | `forktex_cloud.config` | `CloudContext` — controller URL, JWT / account-key, current org + project keys |
 | `forktex_cloud.scaffold` | `forktex cloud init` template generator (ProjectDeployment / StaticSite / SingleContainer / NativeBuild) |
 | `forktex_cloud.bridge` | docker-compose generator (local mode), Loki config, log formatters used by `forktex cloud apply --env local` |

{forktex_cloud-0.5.0 → forktex_cloud-2.0.0}/README.md

@@ -119,7 +119,7 @@ client.vault_delete("POSTGRES_PASSWORD")
 | Module | Purpose |
 |---|---|
 | `forktex_cloud.client` | Typed sync httpx client (`Cloud`) + all OpenAPI-codegenned Pydantic models (`ServerRead`, `ProjectRead`, `EventRead`, `VaultGetResponse`, ...) |
-| `forktex_cloud.manifest` | `Manifest` loader, discriminated-union schema (v1beta2), deep-merge for env overlays, `ManifestError` |
+| `forktex_cloud.manifest` | `Manifest` loader, discriminated-union schema (v1), deep-merge for env overlays, `ManifestError` |
 | `forktex_cloud.config` | `CloudContext` — controller URL, JWT / account-key, current org + project keys |
 | `forktex_cloud.scaffold` | `forktex cloud init` template generator (ProjectDeployment / StaticSite / SingleContainer / NativeBuild) |
 | `forktex_cloud.bridge` | docker-compose generator (local mode), Loki config, log formatters used by `forktex cloud apply --env local` |

{forktex_cloud-0.5.0 → forktex_cloud-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forktex-cloud"
-version = "0.5.0"
+version = "2.0.0"
 description = "Typed Python SDK for the ForkTex Cloud platform — provision, deploy, and manage VPS-backed apps via a declarative manifest."
 authors = [
     {name = "ForkTex", email = "info@forktex.com"}

forktex_cloud-2.0.0/src/forktex_cloud/__init__.py

@@ -0,0 +1,148 @@
+"""forktex_cloud — Standalone Python SDK for the ForkTex Cloud platform.
+
+Usage::
+
+    from forktex_cloud import Cloud
+
+    with Cloud("https://cloud.forktex.com", account_key="ftx-...") as cloud:
+        projects = cloud.list_projects()
+        servers = cloud.list_servers()
+
+Or, when you already hold a ``CloudContext``::
+
+    from forktex_cloud import Cloud, CloudContext
+
+    ctx = CloudContext(controller="https://cloud.forktex.com", account_key="ftx-...")
+    with Cloud.from_context(ctx) as cloud:
+        ...
+
+Loading model — lazy
+--------------------
+
+The SDK is **filesystem-independent**: it deals in data (manifests, compose
+dicts, cipher bytes), never in ``.forktex/`` paths — forktex-py owns the
+on-disk layout. The HTTP client (``Cloud``), the auth/config types
+(``CloudContext``), the manifest loader, and the 17 OpenAPI-codegen models are
+loaded **lazily** via PEP 562 ``__getattr__`` on first access, keeping
+``import forktex_cloud`` cheap. The public surface is unchanged:
+``from forktex_cloud import Cloud`` still works.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+__version__ = "2.0.0"
+
+# ── Lazy attribute map ──────────────────────────────────────────────────────
+#
+# Name → (submodule, attribute). Anything not listed raises AttributeError.
+# Codegen models share one submodule, so first access pays once — subsequent
+# model lookups hit the module-level cache populated by __getattr__.
+_LAZY_ATTRS: dict[str, tuple[str, str]] = {
+    # Client (httpx-backed, heavy)
+    "Cloud": ("forktex_cloud.client.client", "Cloud"),
+    "CloudAPIError": ("forktex_cloud.client.client", "CloudAPIError"),
+    # Config
+    "CloudContext": ("forktex_cloud.config", "CloudContext"),
+    # Manifest
+    "Manifest": ("forktex_cloud.manifest.loader", "Manifest"),
+    "ManifestError": ("forktex_cloud.manifest.loader", "ManifestError"),
+    # Codegen contract + OpenAPI models (all from forktex_cloud.client.generated)
+    "SPEC_HASH": ("forktex_cloud.client.generated", "SPEC_HASH"),
+    "SPEC_VERSION": ("forktex_cloud.client.generated", "SPEC_VERSION"),
+    "ApiKeyCreated": ("forktex_cloud.client.generated", "ApiKeyCreated"),
+    "ApiKeyRead": ("forktex_cloud.client.generated", "ApiKeyRead"),
+    "AuditEventRead": ("forktex_cloud.client.generated", "AuditEventRead"),
+    "EnvironmentRead": ("forktex_cloud.client.generated", "EnvironmentRead"),
+    "HealthRead": ("forktex_cloud.client.generated", "HealthRead"),
+    "JobResponse": ("forktex_cloud.client.generated", "JobResponse"),
+    "MeResponse": ("forktex_cloud.client.generated", "MeResponse"),
+    "OrgRead": ("forktex_cloud.client.generated", "OrgRead"),
+    "ProjectRead": ("forktex_cloud.client.generated", "ProjectRead"),
+    "ServerRead": ("forktex_cloud.client.generated", "ServerRead"),
+    "StatusResponse": ("forktex_cloud.client.generated", "StatusResponse"),
+    "TokenResponse": ("forktex_cloud.client.generated", "TokenResponse"),
+    "UserRead": ("forktex_cloud.client.generated", "UserRead"),
+    "VaultGetResponse": ("forktex_cloud.client.generated", "VaultGetResponse"),
+    "WorkspaceRead": ("forktex_cloud.client.generated", "WorkspaceRead"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 lazy attribute resolver — imports a submodule on first access.
+
+    Once resolved, the attribute is bound on the module so subsequent accesses
+    skip this function entirely (Python looks it up in ``globals()`` first).
+    """
+    if name in _LAZY_ATTRS:
+        import importlib
+
+        module_path, attr_name = _LAZY_ATTRS[name]
+        value = getattr(importlib.import_module(module_path), attr_name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'forktex_cloud' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Include lazy attributes in ``dir()`` so REPL completion still works."""
+    return sorted(set(__all__) | set(globals()))
+
+
+# Static type-checker hint — declared as a TYPE_CHECKING block so it costs
+# nothing at runtime but lets editors / mypy see the eventual symbol types.
+if TYPE_CHECKING:  # pragma: no cover
+    from forktex_cloud.client.client import Cloud, CloudAPIError
+    from forktex_cloud.client.generated import (
+        SPEC_HASH,
+        SPEC_VERSION,
+        ApiKeyCreated,
+        ApiKeyRead,
+        AuditEventRead,
+        EnvironmentRead,
+        HealthRead,
+        JobResponse,
+        MeResponse,
+        OrgRead,
+        ProjectRead,
+        ServerRead,
+        StatusResponse,
+        TokenResponse,
+        UserRead,
+        VaultGetResponse,
+        WorkspaceRead,
+    )
+    from forktex_cloud.config import CloudContext
+    from forktex_cloud.manifest.loader import Manifest, ManifestError
+
+
+__all__ = [
+    # Codegen contract (wire-compatibility markers) — lazy
+    "SPEC_VERSION",
+    "SPEC_HASH",
+    # Client — lazy
+    "Cloud",
+    "CloudAPIError",
+    # Config — lazy
+    "CloudContext",
+    # Manifest — lazy
+    "Manifest",
+    "ManifestError",
+    # Models (from OpenAPI codegen — the single source of truth) — lazy
+    "ApiKeyCreated",
+    "ApiKeyRead",
+    "AuditEventRead",
+    "EnvironmentRead",
+    "HealthRead",
+    "JobResponse",
+    "MeResponse",
+    "OrgRead",
+    "ProjectRead",
+    "ServerRead",
+    "StatusResponse",
+    "TokenResponse",
+    "UserRead",
+    "VaultGetResponse",
+    "WorkspaceRead",
+]

{forktex_cloud-0.5.0 → forktex_cloud-2.0.0}/src/forktex_cloud/bridge/local_compose.py

@@ -6,11 +6,9 @@ No proxy, no blue-green, no SSL -- just plain containers with direct port mappin
 
 from __future__ import annotations
 
-import shutil
 from pathlib import Path
 from typing import Any
 
-from forktex_cloud import paths
 from forktex_cloud.bridge.persistence_defaults import detect_persistence_defaults
 from forktex_cloud.manifest.loader import Manifest
 from forktex_cloud.secrets.base import SecretsProvider
@@ -58,31 +56,37 @@ def _templates_dir() -> Path:
     return Path(__file__).resolve().parent.parent / "templates"
 
 
-def _write_observability_configs(project_root: Path) -> Path:
-    """Copy observability config files to the canonical observability dir."""
-    out_dir = paths.observability_dir(project_root)
-    out_dir.mkdir(parents=True, exist_ok=True)
+def render_observability_configs() -> dict[str, str]:
+    """Return the observability config files as ``{filename: content}``.
+
+    Pure: reads the bundled SDK templates and returns their text. The caller
+    (forktex-py) writes them next to the generated compose file. No ``.forktex/``
+    knowledge here — the SDK only produces data.
+    """
+    out: dict[str, str] = {}
     src_dir = _templates_dir() / "observability"
     if src_dir.is_dir():
-        for src_file in src_dir.iterdir():
+        for src_file in sorted(src_dir.iterdir()):
             if src_file.is_file():
-                shutil.copy2(src_file, out_dir / src_file.name)
-    return out_dir
+                out[src_file.name] = src_file.read_text(encoding="utf-8")
+    return out
 
 
 def _add_observability_services(
     services: dict[str, Any],
     named_volumes: dict[str, Any],
-    project_root: Path,
 ) -> None:
-    """Add Loki + Promtail services."""
-    obs_dir = _write_observability_configs(project_root)
+    """Add Loki + Promtail services.
 
+    The compose file and the ``observability/`` configs are written into the
+    same directory by the caller, so the bind mounts are siblings
+    (``./observability/...``).
+    """
     services["loki"] = {
         "image": "grafana/loki:2.9.0",
         "ports": ["3100:3100"],
         "volumes": [
-            f"../{obs_dir.relative_to(project_root)}/loki.yml:/etc/loki/local-config.yaml:ro",
+            "./observability/loki.yml:/etc/loki/local-config.yaml:ro",
             "loki-data:/loki",
         ],
         "healthcheck": {
@@ -101,7 +105,7 @@ def _add_observability_services(
     services["promtail"] = {
         "image": "grafana/promtail:2.9.0",
         "volumes": [
-            f"../{obs_dir.relative_to(project_root)}/promtail.yml:/etc/promtail/config.yml:ro",
+            "./observability/promtail.yml:/etc/promtail/config.yml:ro",
             "/var/run/docker.sock:/var/run/docker.sock:ro",
             "/var/lib/docker/containers:/var/lib/docker/containers:ro",
         ],
@@ -118,8 +122,16 @@ def local_compose_from_manifest(
     *,
     secrets_provider: SecretsProvider | None = None,
     observability: bool = True,
+    root_prefix: str = "../..",
 ) -> dict[str, Any]:
-    """Build a docker-compose dict suitable for local development."""
+    """Build a docker-compose dict suitable for local development.
+
+    ``root_prefix`` is the relative path from the compose file's directory up to
+    the project root. forktex-py writes the compose into ``.forktex/cache/``
+    (two levels under the root), so the default is ``../..``; build contexts and
+    source bind-mounts are emitted relative to it. (cache-sibling artefacts —
+    ``./observability``, ``./data`` — are unaffected.)
+    """
     services: dict[str, Any] = {}
     named_volumes: dict[str, Any] = {}
     env_name = getattr(manifest, "env_name", None) or "default"
@@ -134,6 +146,35 @@ def local_compose_from_manifest(
         if svc_def.get("type") == "persistence":
             persistence_ids.append(svc_def["id"])
 
+    # Precompute which persistence services WILL get a healthcheck (declared or
+    # from image defaults), independent of generation order. The depends_on
+    # condition derivation below used to read the not-yet-generated persistence
+    # service dict, so services appearing before their DB in the manifest (api,
+    # client, ...) wrongly got ``service_started`` and raced the DB on startup.
+    persistence_has_healthcheck: dict[str, bool] = {}
+    for svc_def in local_services:
+        if svc_def.get("type") != "persistence":
+            continue
+        pid = svc_def["id"]
+        if svc_def.get("healthcheck"):
+            persistence_has_healthcheck[pid] = True
+        else:
+            defaults = detect_persistence_defaults(svc_def.get("image", ""))
+            persistence_has_healthcheck[pid] = bool(defaults and "healthcheck" in defaults)
+
+    # One-shot init services (`labels.forktex.oneshot=true`) — compute
+    # services get an auto-depends_on on each so they're at least ordered
+    # behind the initializer's start. We can't wait on `service_completed`
+    # for a true oneshot the way k8s init-containers do, but the
+    # ``service_started`` ordering closes the most common race (e.g.
+    # gitea-init writes the token file → api can read it on its first
+    # gitea call). The initializer itself self-polls its dependencies.
+    oneshot_ids: list[str] = [
+        svc_def["id"]
+        for svc_def in local_services
+        if (svc_def.get("labels") or {}).get("forktex.oneshot") == "true"
+    ]
+
     for svc_def in local_services:
         sid = svc_def["id"]
         image = svc_def.get("image", "")
@@ -150,22 +191,37 @@ def local_compose_from_manifest(
         if build_cfg and isinstance(build_cfg, dict):
             build_entry: dict[str, str] = {}
             ctx = build_cfg.get("context", f"./{sid}")
-            # Rewrite relative context to be relative to .forktex/ dir
-            build_entry["context"] = f"../{ctx.removeprefix('./')}" if ctx.startswith("./") else ctx
+            # Rewrite a project-relative context to be relative to the compose
+            # file's directory (.forktex/cache/) via root_prefix.
+            build_entry["context"] = (
+                f"{root_prefix}/{ctx.removeprefix('./')}" if ctx.startswith("./") else ctx
+            )
             if build_cfg.get("dockerfile"):
                 build_entry["dockerfile"] = build_cfg["dockerfile"]
             svc["build"] = build_entry
         elif svc_type == "compute":
             dockerfile = project_root / sid / "Dockerfile"
             if dockerfile.is_file():
-                svc["build"] = {"context": f"../{sid}"}
+                svc["build"] = {"context": f"{root_prefix}/{sid}"}
 
         if sid in host_ports:
             host_port = host_ports[sid]
             svc["ports"] = [f"{host_port}:{port}"]
 
-        if svc_type in ("persistence", "observability"):
+        # One-shot init services (e.g. `gitea-init`) carry the
+        # `forktex.oneshot=true` label so the generator skips the implicit
+        # restart-always; they should exit cleanly after their seed step
+        # and stay exited. The label lives on the existing ServiceDef
+        # `labels` field — no schema/codegen change required.
+        is_oneshot = (svc_def.get("labels") or {}).get("forktex.oneshot") == "true"
+        if svc_type in ("persistence", "observability") and not is_oneshot:
             svc["restart"] = "always"
+        if svc_def.get("labels"):
+            svc["labels"] = dict(svc_def["labels"])
+        # docker-compose `pid:` passthrough — `service:<id>` shares another
+        # service's PID namespace so e.g. a sidecar can signal its primary.
+        if svc_def.get("pid"):
+            svc["pid"] = svc_def["pid"]
 
         if svc_type == "persistence":
             defaults = detect_persistence_defaults(image)
@@ -196,7 +252,7 @@ def local_compose_from_manifest(
                     src = v.split(":")[0]
                     rest = v[len(src) :]
                     if src.startswith("./"):
-                        rewritten.append(f"../{src[2:]}{rest}")
+                        rewritten.append(f"{root_prefix}/{src[2:]}{rest}")
                     elif src.startswith("/") or not src.startswith("."):
                         rewritten.append(v)
                         if not src.startswith("/"):
@@ -222,16 +278,19 @@ def local_compose_from_manifest(
         if cmd:
             svc["command"] = cmd
 
-        if svc_type == "compute" and persistence_ids:
+        if svc_type == "compute":
             depends: dict[str, Any] = {}
             for pid in persistence_ids:
-                # Use service_healthy only if the persistence service has a healthcheck
-                psvc = services.get(pid, {})
-                if "healthcheck" in psvc:
-                    depends[pid] = {"condition": "service_healthy"}
-                else:
-                    depends[pid] = {"condition": "service_started"}
-            svc["depends_on"] = depends
+                healthy = persistence_has_healthcheck.get(pid)
+                cond = "service_healthy" if healthy else "service_started"
+                depends[pid] = {"condition": cond}
+            for iid in oneshot_ids:
+                # Initializers run side-by-side; we only need start-ordering,
+                # not completion. The initializer's contract is "write its
+                # output before the first compute request needs it."
+                depends[iid] = {"condition": "service_started"}
+            if depends:
+                svc["depends_on"] = depends
 
         explicit_deps = svc_def.get("depends_on")
         if explicit_deps:
@@ -241,7 +300,7 @@ def local_compose_from_manifest(
         services[sid] = svc
 
     if observability:
-        _add_observability_services(services, named_volumes, project_root)
+        _add_observability_services(services, named_volumes)
 
     compose: dict[str, Any] = {"services": services}
 
@@ -251,26 +310,3 @@ def local_compose_from_manifest(
     compose["networks"] = {"forktex": {}}
 
     return compose
-
-
-def write_local_compose(
-    manifest: Manifest,
-    project_root: Path,
-    *,
-    secrets_provider: SecretsProvider | None = None,
-    observability: bool = True,
-) -> Path:
-    """Generate the local docker-compose file for the project and return its path."""
-    import yaml
-
-    compose = local_compose_from_manifest(
-        manifest,
-        project_root,
-        secrets_provider=secrets_provider,
-        observability=observability,
-    )
-    paths.ensure_project_dirs(project_root)
-    out_path = paths.compose_path(project_root, "local")
-    with open(out_path, "w") as f:
-        yaml.dump(compose, f, default_flow_style=False, sort_keys=False)
-    return out_path

{forktex_cloud-0.5.0 → forktex_cloud-2.0.0}/src/forktex_cloud/client/client.py

@@ -116,9 +116,42 @@ def _merge_fsd_manifest(base: dict, overlay: dict) -> dict:
             merged["cloud"]["services"] = merge_services(
                 base_cloud["services"], over_cloud["services"]
             )
+        # V1 multi-server: same id-aware merge for infrastructure.servers[].
+        # Without this, an overlay's servers[] replaces the base's, dropping
+        # fields the overlay didn't repeat (notably `primary: true`).
+        base_servers = base_cloud.get("infrastructure", {}).get("servers")
+        over_servers = over_cloud.get("infrastructure", {}).get("servers")
+        if isinstance(base_servers, list) and isinstance(over_servers, list):
+            merged.setdefault("cloud", {}).setdefault("infrastructure", {})
+            merged["cloud"]["infrastructure"]["servers"] = merge_services(
+                base_servers, over_servers
+            )
     return merged
 
 
+def _git_head_sha(project_dir: Path) -> str | None:
+    """Return the current HEAD commit SHA if *project_dir* is a git working tree.
+
+    Used to auto-populate ``commit_sha`` on /apply so deploys are traceable to
+    a source revision without requiring the caller to wire it through. Silent
+    on failure (not a git tree, git missing, detached HEAD that errors out).
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=str(project_dir),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    sha = result.stdout.strip()
+    return sha if len(sha) == 40 else None
+
+
 class CloudAPIError(Exception):
     """Raised when the cloud API returns a non-2xx response."""
 
@@ -633,6 +666,8 @@ class Cloud:
         manifest_data: dict | None = None,
         project_dir: Path | None = None,
         image_artifacts: list[dict[str, Any]] | None = None,
+        code_repository_id: str | None = None,
+        commit_sha: str | None = None,
     ) -> JobResponse:
         """Trigger the apply pipeline via POST {org_prefix}/apply.
 
@@ -644,6 +679,12 @@ class Cloud:
         the manifest's compute-service ``image:`` fields are rewritten to
         registry-pinned digest refs, and the index ids are forwarded to the
         controller as ``image_artifact_ids``.
+
+        Lineage: ``commit_sha`` is captured automatically from ``git rev-parse
+        HEAD`` when *project_dir* points at a git working tree and the kwarg
+        isn't already set. ``code_repository_id`` is only meaningful for
+        runner-driven deploys (the runner knows which CodeRepository row it
+        cloned) and is left None for operator invocations.
         """
         body: dict[str, Any] = {
             "skip_dns": skip_dns,
@@ -697,6 +738,15 @@ class Cloud:
             if tarball:
                 body["assets_tarball_b64"] = tarball
 
+        # Auto-detect commit_sha from a git working tree when not explicitly set.
+        if commit_sha is None and project_dir is not None:
+            commit_sha = _git_head_sha(project_dir)
+
+        if code_repository_id:
+            body["code_repository_id"] = code_repository_id
+        if commit_sha:
+            body["commit_sha"] = commit_sha
+
         resp = self._check(self._client.post(f"{self._org_prefix}/apply", json=body))
         return JobResponse.model_validate(resp.json())
 
@@ -845,12 +895,23 @@ class Cloud:
             svc_type = svc.get("type", "compute")
             service_prefix = f"services/{svc_id}"
 
-            # Volume-mounted local files and directories
+            # Volume-mounted local files and directories.
+            #
+            # Only RELATIVE local paths (./foo, ../bar) are treated as
+            # tarball-worthy assets — they're project-local source dirs the
+            # deploy needs to ship.
+            #
+            # Absolute paths in `volumes:` (e.g. /media/megatyres/db) are
+            # by convention **server-side host paths** on the deployment
+            # target, NOT local asset directories. Tarballing them is
+            # always wrong (they may not exist locally; if they do, the
+            # permissions are whatever the local OS happens to assign,
+            # which has nothing to do with the deploy). Skip them.
             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("/"):
+                    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