forktex-cloud 0.2.3__py3-none-any.whl

forktex_cloud/__init__.py

@@ -0,0 +1,92 @@
+# 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/>.
+
+"""forktex_cloud — Standalone Python SDK for the ForkTex Cloud platform.
+
+Usage::
+
+    from forktex_cloud import ForktexCloudClient, CloudContext
+
+    ctx = CloudContext(controller="https://cloud.forktex.com", account_key="ftx-...")
+    with ForktexCloudClient.from_context(ctx) as client:
+        projects = client.list_projects()
+        servers = client.list_servers()
+"""
+
+__version__ = "0.2.3"
+
+from forktex_cloud import paths
+from forktex_cloud.client.client import CloudAPIError, ForktexCloudClient
+from forktex_cloud.client.generated import (
+    SPEC_HASH,
+    SPEC_VERSION,
+    ApiKeyCreated,
+    ApiKeyRead,
+    EnvironmentRead,
+    EventRead,
+    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__ = [
+    # Filesystem layout spec (V1)
+    "paths",
+    # Codegen contract (wire-compatibility markers)
+    "SPEC_VERSION",
+    "SPEC_HASH",
+    # Client
+    "ForktexCloudClient",
+    "CloudAPIError",
+    # Config
+    "CloudContext",
+    # Manifest
+    "Manifest",
+    "ManifestError",
+    # Models (from OpenAPI codegen — the single source of truth)
+    "ApiKeyCreated",
+    "ApiKeyRead",
+    "EnvironmentRead",
+    "EventRead",
+    "HealthRead",
+    "JobResponse",
+    "MeResponse",
+    "OrgRead",
+    "ProjectRead",
+    "ServerRead",
+    "StatusResponse",
+    "TokenResponse",
+    "UserRead",
+    "VaultGetResponse",
+    "WorkspaceRead",
+]

forktex_cloud/bridge/__init__.py

@@ -0,0 +1,24 @@
+# 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/>.
+
+"""Bridge modules: manifest-to-Docker Compose for local dev."""

forktex_cloud/bridge/local_compose.py

@@ -0,0 +1,295 @@
+# 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 -> local docker-compose generator.
+
+Generates a simple local-oriented docker-compose.local.yml from a forktex manifest.
+No proxy, no blue-green, no SSL -- just plain containers with direct port mapping.
+"""
+
+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
+
+# Ports reserved by observability services (Loki)
+_OBSERVABILITY_PORTS = {3100}
+
+
+def _allocate_host_ports(
+    services: list[dict[str, Any]],
+    *,
+    reserved: set[int] | None = None,
+) -> dict[str, int]:
+    """Allocate host ports for compute services, avoiding conflicts."""
+    used: set[int] = set(reserved or ())
+    mapping: dict[str, int] = {}
+
+    # First pass: claim explicit hostPort values (any type)
+    for svc in services:
+        hp = svc.get("hostPort")
+        if hp is not None:
+            mapping[svc["id"]] = int(hp)
+            used.add(int(hp))
+
+    # Second pass: auto-assign only compute services
+    for svc in services:
+        sid = svc["id"]
+        if sid in mapping:
+            continue
+        svc_type = svc.get("type", "compute")
+        if svc_type != "compute":
+            continue
+        port = svc.get("port", 80)
+        candidate = 8080 if port == 80 else port
+        while candidate in used:
+            candidate += 1
+        mapping[sid] = candidate
+        used.add(candidate)
+
+    return mapping
+
+
+def _templates_dir() -> Path:
+    """Locate the forktex/cloud/templates/ directory."""
+    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)
+    src_dir = _templates_dir() / "observability"
+    if src_dir.is_dir():
+        for src_file in src_dir.iterdir():
+            if src_file.is_file():
+                shutil.copy2(src_file, out_dir / src_file.name)
+    return out_dir
+
+
+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)
+
+    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",
+            "loki-data:/loki",
+        ],
+        "healthcheck": {
+            "test": [
+                "CMD-SHELL",
+                "wget --quiet --tries=1 --output-document=- http://localhost:3100/ready || exit 1",
+            ],
+            "interval": "10s",
+            "timeout": "5s",
+            "retries": 5,
+        },
+        "networks": ["forktex"],
+    }
+    named_volumes["loki-data"] = None
+
+    services["promtail"] = {
+        "image": "grafana/promtail:2.9.0",
+        "volumes": [
+            f"../{obs_dir.relative_to(project_root)}/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",
+        ],
+        "depends_on": {
+            "loki": {"condition": "service_healthy"},
+        },
+        "networks": ["forktex"],
+    }
+
+
+def local_compose_from_manifest(
+    manifest: Manifest,
+    project_root: Path,
+    *,
+    secrets_provider: SecretsProvider | None = None,
+    observability: bool = True,
+) -> dict[str, Any]:
+    """Build a docker-compose dict suitable for local development."""
+    services: dict[str, Any] = {}
+    named_volumes: dict[str, Any] = {}
+    env_name = getattr(manifest, "env_name", None) or "default"
+
+    local_services = manifest.services_for_env(env=manifest.env_name or "local")
+
+    reserved = _OBSERVABILITY_PORTS if observability else set()
+    host_ports = _allocate_host_ports(local_services, reserved=reserved)
+
+    persistence_ids: list[str] = []
+    for svc_def in local_services:
+        if svc_def.get("type") == "persistence":
+            persistence_ids.append(svc_def["id"])
+
+    for svc_def in local_services:
+        sid = svc_def["id"]
+        image = svc_def.get("image", "")
+        port = svc_def.get("port", 80)
+        svc_type = svc_def.get("type", "compute")
+
+        svc: dict[str, Any] = {"image": image}
+
+        if svc_type == "compute":
+            build_cfg = svc_def.get("build")
+            if build_cfg and isinstance(build_cfg, dict):
+                # Use explicit build config from manifest overlay
+                build_entry: dict[str, str] = {}
+                ctx = build_cfg.get("context", f"./{sid}")
+                # Rewrite relative context to be relative to .forktex/ dir
+                if ctx.startswith("./"):
+                    build_entry["context"] = f"../{ctx[2:]}"
+                else:
+                    build_entry["context"] = ctx
+                if build_cfg.get("dockerfile"):
+                    build_entry["dockerfile"] = build_cfg["dockerfile"]
+                svc["build"] = build_entry
+            else:
+                dockerfile = project_root / sid / "Dockerfile"
+                if dockerfile.is_file():
+                    svc["build"] = {"context": f"../{sid}"}
+
+        if sid in host_ports:
+            host_port = host_ports[sid]
+            svc["ports"] = [f"{host_port}:{port}"]
+
+        if svc_type in ("persistence", "observability"):
+            svc["restart"] = "always"
+
+        if svc_type == "persistence":
+            defaults = detect_persistence_defaults(image)
+            if defaults and "healthcheck" in defaults:
+                svc["healthcheck"] = defaults["healthcheck"]
+
+        if svc_def.get("healthcheck"):
+            svc["healthcheck"] = svc_def["healthcheck"]
+
+        comp_env = svc_def.get("environment")
+        if comp_env:
+            comp_env = dict(comp_env) if isinstance(comp_env, dict) else list(comp_env)
+            if isinstance(comp_env, dict) and secrets_provider:
+                from forktex_cloud.secrets.resolver import (
+                    has_vault_references,
+                    resolve_secrets,
+                )
+
+                if has_vault_references(comp_env):
+                    comp_env = resolve_secrets(comp_env, secrets_provider, env_name)
+            svc["environment"] = comp_env
+
+        vols = svc_def.get("volumes")
+        if vols:
+            rewritten: list[str] = []
+            for v in vols:
+                if isinstance(v, str) and ":" in v:
+                    src = v.split(":")[0]
+                    rest = v[len(src) :]
+                    if src.startswith("./"):
+                        rewritten.append(f"../{src[2:]}{rest}")
+                    elif src.startswith("/") or not src.startswith("."):
+                        rewritten.append(v)
+                        if not src.startswith("/"):
+                            named_volumes[src] = None
+                    else:
+                        rewritten.append(v)
+                else:
+                    rewritten.append(v)
+            svc["volumes"] = rewritten
+        elif svc_type == "persistence":
+            defaults = detect_persistence_defaults(image)
+            if defaults and defaults.get("default_volume"):
+                vol_name = f"{sid}-data"
+                svc["volumes"] = [f"{vol_name}:{defaults['default_volume']}"]
+                named_volumes[vol_name] = None
+
+        cmd = svc_def.get("command")
+        if cmd:
+            svc["command"] = cmd
+
+        if svc_type == "compute" and persistence_ids:
+            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
+
+        explicit_deps = svc_def.get("depends_on")
+        if explicit_deps:
+            svc["depends_on"] = list(explicit_deps)
+
+        svc["networks"] = ["forktex"]
+        services[sid] = svc
+
+    if observability:
+        _add_observability_services(services, named_volumes, project_root)
+
+    compose: dict[str, Any] = {"services": services}
+
+    if named_volumes:
+        compose["volumes"] = {name: {} for name in named_volumes}
+
+    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/bridge/log_formatter.py

@@ -0,0 +1,62 @@
+# 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/>.
+
+"""ANSI color formatting for log output."""
+
+from __future__ import annotations
+
+import time
+
+# 8 distinct ANSI colors for service names
+COLORS = [
+    "\033[36m",  # cyan
+    "\033[32m",  # green
+    "\033[33m",  # yellow
+    "\033[35m",  # magenta
+    "\033[34m",  # blue
+    "\033[31m",  # red
+    "\033[37m",  # white
+    "\033[96m",  # bright cyan
+]
+
+DIM = "\033[2m"
+RESET = "\033[0m"
+
+
+def assign_colors(service_ids: list[str]) -> dict[str, str]:
+    """Assign a distinct ANSI color to each service (round-robin)."""
+    return {sid: COLORS[i % len(COLORS)] for i, sid in enumerate(sorted(service_ids))}
+
+
+def format_line(
+    ts_ns: int,
+    service: str,
+    line: str,
+    color: str,
+    max_name_len: int,
+) -> str:
+    """Format a single log line with timestamp, colored service name, and separator."""
+    t = time.gmtime(ts_ns // 1_000_000_000)
+    ts_str = time.strftime("%H:%M:%S", t)
+    padded = service.ljust(max_name_len)
+    return f"{DIM}{ts_str}{RESET} {color}{padded}{RESET} {DIM}|{RESET} {line}"

forktex_cloud/bridge/loki.py

@@ -0,0 +1,109 @@
+# 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/>.
+
+"""Thin Loki HTTP API client using stdlib only."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Iterator
+
+
+def loki_ready(base_url: str = "http://localhost:3100") -> bool:
+    """Return True if Loki is reachable and ready."""
+    try:
+        req = urllib.request.Request(f"{base_url}/ready", method="GET")
+        with urllib.request.urlopen(req, timeout=2) as resp:
+            return resp.status == 200
+    except (urllib.error.URLError, OSError):
+        return False
+
+
+def build_logql(services: list[str] | None = None) -> str:
+    """Build a LogQL stream selector."""
+    if not services:
+        return '{job="docker"}'
+    if len(services) == 1:
+        return f'{{service="{services[0]}"}}'
+    return '{service=~"' + "|".join(services) + '"}'
+
+
+def _parse_streams(data: dict) -> list[tuple[int, str, str]]:
+    """Parse Loki query_range response into (timestamp_ns, service, line) tuples."""
+    entries: list[tuple[int, str, str]] = []
+    for stream in data.get("data", {}).get("result", []):
+        labels = stream.get("stream", {})
+        service = labels.get("service", labels.get("container", "unknown"))
+        for ts_ns_str, line in stream.get("values", []):
+            entries.append((int(ts_ns_str), service, line))
+    entries.sort(key=lambda e: e[0])
+    return entries
+
+
+def query_range(
+    base_url: str,
+    logql: str,
+    start_ns: int,
+    end_ns: int,
+    limit: int = 5000,
+) -> list[tuple[int, str, str]]:
+    """Query Loki for log entries in a time range."""
+    params = urllib.parse.urlencode(
+        {
+            "query": logql,
+            "start": str(start_ns),
+            "end": str(end_ns),
+            "limit": str(limit),
+            "direction": "forward",
+        }
+    )
+    url = f"{base_url}/loki/api/v1/query_range?{params}"
+    req = urllib.request.Request(url, method="GET")
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        body = json.loads(resp.read().decode())
+    return _parse_streams(body)
+
+
+def tail(
+    base_url: str,
+    logql: str,
+    start_ns: int,
+    poll_interval: float = 2.0,
+) -> Iterator[tuple[int, str, str]]:
+    """Poll Loki for new entries, yielding (timestamp_ns, service, line)."""
+    last_ts = start_ns
+    while True:
+        now_ns = int(time.time() * 1_000_000_000)
+        try:
+            entries = query_range(base_url, logql, last_ts + 1, now_ns)
+        except (urllib.error.URLError, OSError):
+            return
+        for ts_ns, service, line in entries:
+            yield (ts_ns, service, line)
+            if ts_ns > last_ts:
+                last_ts = ts_ns
+        time.sleep(poll_interval)