gagarin 0.1.1__tar.gz

gagarin-0.1.1/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+dist/
+build/

gagarin-0.1.1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: gagarin
+Version: 0.1.1
+Summary: Python client for the gagarin API: run jobs from images already in the gagarin registry.
+Project-URL: Repository, https://github.com/gagarin-cloud/sdk
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# gagarin — Python
+
+```sh
+pip install gagarin
+```
+
+Python 3.9+, standard library only.
+
+```python
+from gagarin import Gagarin, GagarinError
+
+gg = Gagarin()  # GAGARIN_TOKEN, GAGARIN_API; or Gagarin(token=...)
+
+# What `gg run` does: submit, wait, exit with the script's code.
+res = gg.jobs.run_and_wait(
+    "shop", "migrate",
+    image="migrate:v3",  # or registry.gagarin.cloud/<project-id>/migrate:v3
+    env={"LOG_LEVEL": "debug"},
+    deps=["db"],
+    size="m",
+    timeout_seconds=900,
+    on_update=lambda run: print(run.phase),
+)
+raise SystemExit(res.exit_code)
+```
+
+Fire and forget, then check later:
+
+```python
+sub = gg.jobs.run("shop", "backfill", image="backfill:v1")
+run = gg.jobs.wait("shop", "backfill", sub.revision)
+print(gg.jobs.logs("shop", "backfill", since="30m")["logs"])
+```
+
+A scheduled job (runs nothing now):
+
+```python
+gg.jobs.run("shop", "nightly", image="report:v2", schedule="0 3 * * *", time_zone="Europe/Berlin")
+```
+
+The basics (answers are plain dicts, typed with `TypedDict`):
+
+```python
+me = gg.account.whoami()                 # me["account"], me["can"], me["registry"]
+bill = gg.account.billing()              # bill["balance"], bill["runway_hours"]
+projects = gg.projects.list()
+p = gg.projects.create("shop")           # raises project_exists if you have one
+st = gg.projects.status("shop")          # st["services"], st["notices"], st["usage_today"]
+web = gg.projects.service_status("shop", "web")
+logs = gg.services.logs("shop", "web", since="1h", contains="error")
+history = gg.services.deployments("shop", "web")
+health = gg.platform.health()            # an unhealthy platform is an answer, not an exception
+```
+
+API refusals raise `GagarinError` with `status`, `code`, `message` and `fix_hint`.
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests
+```

gagarin-0.1.1/README.md

@@ -0,0 +1,59 @@
+# gagarin — Python
+
+```sh
+pip install gagarin
+```
+
+Python 3.9+, standard library only.
+
+```python
+from gagarin import Gagarin, GagarinError
+
+gg = Gagarin()  # GAGARIN_TOKEN, GAGARIN_API; or Gagarin(token=...)
+
+# What `gg run` does: submit, wait, exit with the script's code.
+res = gg.jobs.run_and_wait(
+    "shop", "migrate",
+    image="migrate:v3",  # or registry.gagarin.cloud/<project-id>/migrate:v3
+    env={"LOG_LEVEL": "debug"},
+    deps=["db"],
+    size="m",
+    timeout_seconds=900,
+    on_update=lambda run: print(run.phase),
+)
+raise SystemExit(res.exit_code)
+```
+
+Fire and forget, then check later:
+
+```python
+sub = gg.jobs.run("shop", "backfill", image="backfill:v1")
+run = gg.jobs.wait("shop", "backfill", sub.revision)
+print(gg.jobs.logs("shop", "backfill", since="30m")["logs"])
+```
+
+A scheduled job (runs nothing now):
+
+```python
+gg.jobs.run("shop", "nightly", image="report:v2", schedule="0 3 * * *", time_zone="Europe/Berlin")
+```
+
+The basics (answers are plain dicts, typed with `TypedDict`):
+
+```python
+me = gg.account.whoami()                 # me["account"], me["can"], me["registry"]
+bill = gg.account.billing()              # bill["balance"], bill["runway_hours"]
+projects = gg.projects.list()
+p = gg.projects.create("shop")           # raises project_exists if you have one
+st = gg.projects.status("shop")          # st["services"], st["notices"], st["usage_today"]
+web = gg.projects.service_status("shop", "web")
+logs = gg.services.logs("shop", "web", since="1h", contains="error")
+history = gg.services.deployments("shop", "web")
+health = gg.platform.health()            # an unhealthy platform is an answer, not an exception
+```
+
+API refusals raise `GagarinError` with `status`, `code`, `message` and `fix_hint`.
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests
+```

gagarin-0.1.1/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gagarin"
+version = "0.1.1"
+description = "Python client for the gagarin API: run jobs from images already in the gagarin registry."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/gagarin-cloud/sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gagarin"]

gagarin-0.1.1/src/gagarin/__init__.py

@@ -0,0 +1,58 @@
+"""A client for the gagarin API.
+
+Its first job is the one ``gg run`` does: start a job from an image that is
+already in gagarin's registry, and optionally wait for it to finish.
+
+    from gagarin import Gagarin
+
+    gg = Gagarin()  # GAGARIN_TOKEN, GAGARIN_API
+    res = gg.jobs.run_and_wait("shop", "migrate", image="migrate:v3", deps=["db"])
+    raise SystemExit(res.exit_code)
+
+Around it are the basics: ``account``, ``projects`` (with their status),
+``services`` (logs and history) and ``platform`` (gagarin's own health).
+"""
+
+from .account import Account
+from .client import DEFAULT_BASE_URL, DEFAULT_REGISTRY, Gagarin, Transport
+from .errors import GagarinError, SupersededError, SuspendedError, WaitTimeout
+from .jobs import (
+    DONE,
+    FAILED,
+    MAX_TIMEOUT_SECONDS,
+    PENDING,
+    RUNNING,
+    SUSPENDED,
+    Jobs,
+    RunResult,
+    RunState,
+    Submission,
+)
+from .platform import Platform
+from .projects import Projects
+from .services import Services
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_REGISTRY",
+    "DONE",
+    "FAILED",
+    "MAX_TIMEOUT_SECONDS",
+    "PENDING",
+    "RUNNING",
+    "SUSPENDED",
+    "Account",
+    "Gagarin",
+    "GagarinError",
+    "Jobs",
+    "Platform",
+    "Projects",
+    "RunResult",
+    "RunState",
+    "Services",
+    "Submission",
+    "SupersededError",
+    "SuspendedError",
+    "Transport",
+    "WaitTimeout",
+]

gagarin-0.1.1/src/gagarin/account.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .types import Billing, Whoami
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import Gagarin
+
+
+class Account:
+    """The account the credential belongs to."""
+
+    def __init__(self, client: Gagarin):
+        self._c = client
+
+    def whoami(self) -> Whoami:
+        """Which account this credential acts as, and what it may do
+        (``can`` holds ``"deploy"`` and/or ``"destroy"``)."""
+        return self._c.request("GET", "/v1/whoami")
+
+    def billing(self) -> Billing:
+        """The account's balance, burn and runway, in micro-USD."""
+        return self._c.request("GET", "/v1/billing")

gagarin-0.1.1/src/gagarin/client.py

@@ -0,0 +1,133 @@
+"""The client, and the one place requests are made."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Mapping, Optional, Tuple
+
+from .errors import api_error
+
+DEFAULT_BASE_URL = "https://api.gagarin.cloud"
+DEFAULT_REGISTRY = "registry.gagarin.cloud"
+
+#: (method, url, headers, body) -> (status, body). Replaceable to use a
+#: different HTTP stack.
+Transport = Callable[[str, str, Mapping[str, str], Optional[bytes]], Tuple[int, bytes]]
+
+
+def _urllib_transport(timeout: float) -> Transport:
+    def send(method: str, url: str, headers: Mapping[str, str], body: bytes | None) -> tuple[int, bytes]:
+        req = urllib.request.Request(url, data=body, method=method, headers=dict(headers))
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return resp.status, resp.read()
+        except urllib.error.HTTPError as e:
+            return e.code, e.read()
+
+    return send
+
+
+def quote(s: str) -> str:
+    return urllib.parse.quote(s, safe="")
+
+
+def project_path(project: str) -> str:
+    return f"/v1/projects/{quote(project)}"
+
+
+def service_path(project: str, name: str) -> str:
+    return f"{project_path(project)}/services/{quote(name)}"
+
+
+class Gagarin:
+    """A client for the gagarin API.
+
+    - ``jobs``: submit, wait on and read jobs — what ``gg run`` does.
+    - ``account``: who the credential is, and the account's balance.
+    - ``projects``: list, create and read projects, and their status.
+    - ``services``: any service's logs and deploy history.
+    - ``platform``: whether gagarin itself is working.
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str | None = None,
+        registry: str | None = None,
+        *,
+        timeout: float = 120.0,
+        transport: Transport | None = None,
+    ):
+        """``token`` defaults to ``$GAGARIN_TOKEN``, ``base_url`` to ``$GAGARIN_API``
+        and ``registry`` to ``$GAGARIN_REGISTRY``."""
+        from .account import Account
+        from .jobs import Jobs
+        from .platform import Platform
+        from .projects import Projects
+        from .services import Services
+
+        token = token or os.environ.get("GAGARIN_TOKEN")
+        if not token:
+            raise ValueError("gagarin: no token: pass token= or set GAGARIN_TOKEN")
+        self._token = token
+        self._base_url = (base_url or os.environ.get("GAGARIN_API") or DEFAULT_BASE_URL).rstrip("/")
+        self._registry = (registry or os.environ.get("GAGARIN_REGISTRY") or DEFAULT_REGISTRY).rstrip("/")
+        self._send = transport or _urllib_transport(timeout)
+        self.jobs = Jobs(self)
+        self.account = Account(self)
+        self.projects = Projects(self)
+        self.services = Services(self)
+        self.platform = Platform(self)
+
+    def send(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+    ) -> tuple[int, bytes]:
+        """Makes one request and hands back the status and body, whatever the status was."""
+        url = self._base_url + path
+        q = {}
+        for k, v in (query or {}).items():
+            if v is None or v == "" or v is False:
+                continue
+            q[k] = "true" if v is True else str(v)
+        if q:
+            url += "?" + urllib.parse.urlencode(q)
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+            "User-Agent": "gagarin-sdk-python",
+        }
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode()
+        return self._send(method, url, headers, data)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+    ) -> Any:
+        """Makes one request, raises :class:`GagarinError` on a refusal, and parses the answer."""
+        status, raw = self.send(method, path, query=query, body=body)
+        if not 200 <= status < 300:
+            raise api_error(status, raw)
+        return json.loads(raw) if raw else None
+
+    def image_ref(self, project: str, image: str) -> str:
+        """Expands a bare ``migrate:v3`` into the full reference gagarin runs from.
+        A reference that already contains a ``/`` is returned unchanged."""
+        if "/" in image:
+            return image
+        return f"{self._registry}/{self.projects.get(project)['id']}/{image}"

gagarin-0.1.1/src/gagarin/errors.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+
+
+class GagarinError(Exception):
+    """What the API answers when it refuses a request. Branch on ``code``."""
+
+    def __init__(self, status: int, code: str, message: str, fix_hint: str | None = None):
+        self.status = status
+        self.code = code
+        self.message = message
+        self.fix_hint = fix_hint
+        text = f"[{code}] {message}"
+        if fix_hint:
+            text += f"\nhint: {fix_hint}"
+        super().__init__(text)
+
+
+class SupersededError(GagarinError):
+    """A newer run of the job started before the awaited one was seen to finish."""
+
+
+class SuspendedError(GagarinError):
+    """The project was suspended, which stops its runs."""
+
+
+class WaitTimeout(GagarinError):
+    """The run had not finished when the wait gave up."""
+
+
+def api_error(status: int, raw: bytes) -> GagarinError:
+    """The error for a refusal, from the API's envelope when there is one."""
+    err = None
+    try:
+        err = json.loads(raw).get("error")
+    except (ValueError, AttributeError):
+        pass
+    if isinstance(err, dict) and err.get("code"):
+        return GagarinError(status, err["code"], err.get("message", ""), err.get("fix_hint"))
+    return GagarinError(status, f"http_{status}", raw.decode(errors="replace").strip())

gagarin-0.1.1/src/gagarin/jobs.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Mapping, Sequence
+
+from .client import service_path
+from .errors import GagarinError, SupersededError, SuspendedError, WaitTimeout
+from .types import Logs, ServiceStatus
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import Gagarin
+
+#: The longest a run may take, and what a new job gets.
+MAX_TIMEOUT_SECONDS = 3600
+
+PENDING, RUNNING, DONE, FAILED, SUSPENDED = "pending", "running", "done", "failed", "suspended"
+
+
+@dataclass(frozen=True)
+class RunState:
+    """What a run did."""
+
+    revision: int
+    phase: str
+    exit_code: int | None = None
+    started_at: str | None = None
+    finished_at: str | None = None
+
+    @property
+    def finished(self) -> bool:
+        return self.phase in (DONE, FAILED)
+
+    @property
+    def succeeded(self) -> bool:
+        return self.phase == DONE and (self.exit_code is None or self.exit_code == 0)
+
+    @classmethod
+    def from_json(cls, d: Mapping[str, Any]) -> RunState:
+        return cls(
+            revision=d["revision"],
+            phase=d["phase"],
+            exit_code=d.get("exit_code"),
+            started_at=d.get("started_at"),
+            finished_at=d.get("finished_at"),
+        )
+
+
+@dataclass(frozen=True)
+class Submission:
+    """The job as stored, and the revision this run is — the run's name."""
+
+    project: str
+    name: str
+    revision: int
+    image: str
+    kind: str = "job"
+    size: str | None = None
+    digest: str | None = None
+    timeout_seconds: int | None = None
+    schedule: str | None = None
+    time_zone: str | None = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_json(cls, d: Mapping[str, Any]) -> Submission:
+        return cls(
+            project=d["project"],
+            name=d["name"],
+            revision=d["revision"],
+            image=d["image"],
+            kind=d.get("kind", "job"),
+            size=d.get("size"),
+            digest=d.get("digest"),
+            timeout_seconds=d.get("timeout_seconds"),
+            schedule=d.get("schedule"),
+            time_zone=d.get("time_zone"),
+            raw=d,
+        )
+
+
+@dataclass(frozen=True)
+class RunResult:
+    """A submission and how its run ended."""
+
+    submission: Submission
+    run: RunState
+
+    @property
+    def exit_code(self) -> int:
+        """The script's own exit code, 0 on success, 1 for a run that failed
+        without one — what ``gg run`` exits with."""
+        if self.run.exit_code is not None:
+            return self.run.exit_code
+        return 0 if self.run.phase == DONE else 1
+
+
+def _retryable(e: Exception) -> bool:
+    if isinstance(e, GagarinError):
+        return e.status >= 500 or e.status == 429
+    return isinstance(e, OSError)
+
+
+class Jobs:
+    """Jobs: images that run to completion and listen on nothing."""
+
+    def __init__(self, client: Gagarin):
+        self._c = client
+
+    def run(
+        self,
+        project: str,
+        name: str,
+        *,
+        image: str,
+        digest: str | None = None,
+        env: Mapping[str, str] | None = None,
+        deps: Sequence[str] | None = None,
+        size: str | None = None,
+        timeout_seconds: int | None = None,
+        schedule: str | None = None,
+        time_zone: str | None = None,
+    ) -> Submission:
+        """Submits a run of the named job and returns without waiting.
+
+        As with ``gg run``, the image must already be in gagarin's registry: a
+        full reference, or a bare ``migrate:v3`` expanded against the project.
+        Every call is a new run and a new revision.
+
+        - ``digest``: ``sha256:...`` as docker push reported it, pinning the image.
+        - ``env``: the complete environment for this run. Replaces the job's;
+          not merged, and ``None`` empties it.
+        - ``deps``: resources and services this run may reach, added to what the
+          job already declares. A migration must name its database here.
+        - ``size``: ``"s"``, ``"m"`` or ``"l"``. ``None`` keeps the current size.
+        - ``timeout_seconds``: 1–3600, counted from submission. ``None`` keeps it.
+        - ``schedule``: five cron fields or ``@daily``-style. Nothing runs now;
+          each firing is a run. Cannot be removed except by destroying the job.
+        - ``time_zone``: IANA zone the schedule is read in. ``None`` keeps it.
+        """
+        if not image:
+            raise ValueError("gagarin: image is required")
+        # The environment is replaced on every run, so it is always sent.
+        body: dict[str, Any] = {"kind": "job", "image": self._c.image_ref(project, image), "env": dict(env or {})}
+        if digest:
+            body["digest"] = digest
+        if deps:
+            body["deps"] = list(deps)
+        if size:
+            body["size"] = size
+        if timeout_seconds:
+            body["timeout_seconds"] = timeout_seconds
+        if schedule:
+            body["schedule"] = schedule
+        if time_zone:
+            body["time_zone"] = time_zone
+        return Submission.from_json(self._c.request("PUT", service_path(project, name), body=body))
+
+    def get(self, project: str, name: str) -> ServiceStatus:
+        """The job's row from the project's status, with how its latest run went
+        in ``actual.run``. A name that is not a job is refused ``not_a_job``."""
+        row = self._c.projects.service_status(project, name)
+        if row.get("kind") != "job":
+            raise GagarinError(409, "not_a_job", f"{name} is a {row.get('kind')} in this project, not a job")
+        return row
+
+    def wait(
+        self,
+        project: str,
+        name: str,
+        revision: int,
+        *,
+        poll_interval: float = 3.0,
+        timeout: float = 65 * 60,
+        on_update: Callable[[RunState], None] | None = None,
+    ) -> RunState:
+        """Blocks until the given revision of the job has finished, and returns
+        how it ended. A failed run is not an exception: read ``phase`` and
+        ``exit_code``. The default timeout outlasts the platform's 60 minutes.
+
+        Raises :class:`SupersededError` if a newer run starts first,
+        :class:`SuspendedError` if the project is suspended, and
+        :class:`WaitTimeout` when ``timeout`` passes."""
+        deadline = time.monotonic() + timeout
+        last_phase, transient = None, 0
+        while True:
+            d = None
+            try:
+                d = (self.get(project, name).get("actual") or {}).get("run")
+                transient = 0
+            except Exception as e:
+                if not _retryable(e) or transient >= 5:
+                    raise
+                transient += 1
+            if d:
+                run = RunState.from_json(d)
+                if run.revision > revision:
+                    raise SupersededError(
+                        409, "superseded", f"run {revision} of {name} was superseded by run {run.revision}"
+                    )
+                if run.revision == revision:
+                    if run.phase != last_phase and on_update:
+                        on_update(run)
+                    last_phase = run.phase
+                    if run.finished:
+                        return run
+                    if run.phase == SUSPENDED:
+                        raise SuspendedError(
+                            409, "suspended", f"the project is suspended and run {revision} of {name} was stopped"
+                        )
+            if time.monotonic() + poll_interval > deadline:
+                raise WaitTimeout(408, "wait_timeout", f"run {revision} of {name} had not finished in time")
+            time.sleep(poll_interval)
+
+    def run_and_wait(
+        self,
+        project: str,
+        name: str,
+        *,
+        poll_interval: float = 3.0,
+        timeout: float = 65 * 60,
+        on_update: Callable[[RunState], None] | None = None,
+        **run_options: Any,
+    ) -> RunResult:
+        """Submits a run and waits for it to finish — what ``gg run`` does.
+        Takes the settings :meth:`run` takes, except ``schedule``."""
+        if run_options.get("schedule"):
+            raise ValueError("gagarin: a scheduled job does not run now; submit it with run()")
+        sub = self.run(project, name, **run_options)
+        run = self.wait(project, name, sub.revision, poll_interval=poll_interval, timeout=timeout, on_update=on_update)
+        return RunResult(submission=sub, run=run)
+
+    def logs(self, project: str, name: str, **options: Any) -> Logs:
+        """The job's logs; takes the filters :meth:`Services.logs` takes."""
+        return self._c.services.logs(project, name, **options)

gagarin-0.1.1/src/gagarin/platform.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from .errors import api_error
+from .types import Health
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import Gagarin
+
+
+class Platform:
+    """Whether gagarin itself is working."""
+
+    def __init__(self, client: Gagarin):
+        self._c = client
+
+    def health(self) -> Health:
+        """The platform's health. An unhealthy platform is an answer, not an
+        exception: read ``ok`` and each check's ``detail``. An exception means
+        the API could not be asked at all."""
+        status, raw = self._c.send("GET", "/healthz/platform")
+        if status in (200, 503):
+            try:
+                return json.loads(raw)
+            except ValueError:
+                pass
+        raise api_error(status, raw)