runta-sdk 0.0.4__py3-none-any.whl

asyncrunta/__init__.py

@@ -0,0 +1,45 @@
+"""Async Runta Python SDK."""
+
+from .client import AsyncRunta, Runtime, Session
+from .errors import ApiError, CommandError, ConfigError, RuntaError
+from .models import (
+    CommandResult,
+    CpuArch,
+    EgressAuditEvent,
+    EgressPolicy,
+    Injection,
+    IngressSpec,
+    RuntimeInfo,
+    RuntimeStatus,
+    SecretInfo,
+    SecretInjectionRuleInfo,
+    SecretRuleInfo,
+    SnapshotInfo,
+    SnapshotState,
+)
+
+Runta = AsyncRunta
+
+__all__ = [
+    "ApiError",
+    "AsyncRunta",
+    "CommandError",
+    "CommandResult",
+    "ConfigError",
+    "CpuArch",
+    "EgressAuditEvent",
+    "EgressPolicy",
+    "Injection",
+    "IngressSpec",
+    "Runta",
+    "RuntaError",
+    "Runtime",
+    "RuntimeInfo",
+    "RuntimeStatus",
+    "SecretInfo",
+    "SecretInjectionRuleInfo",
+    "SecretRuleInfo",
+    "Session",
+    "SnapshotInfo",
+    "SnapshotState",
+]

asyncrunta/_config.py

@@ -0,0 +1,69 @@
+"""Configuration resolution."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+from .errors import ConfigError
+
+
+def resolve_config(
+    *,
+    endpoint: str | None,
+    token: str | None,
+    config_path: str | Path | None,
+) -> tuple[str, str]:
+    file_config = _read_config(config_path)
+    resolved_endpoint = _clean(endpoint) or _clean(os.getenv("RUNTA_ENDPOINT")) or file_config[0]
+    resolved_token = (
+        _clean(token)
+        or _clean(os.getenv("RUNTA_TOKEN"))
+        or _read_token_file(os.getenv("RUNTA_TOKEN_FILE"))
+        or file_config[1]
+    )
+    if not resolved_endpoint:
+        raise ConfigError(
+            "missing endpoint: pass endpoint=..., set RUNTA_ENDPOINT, or set endpoint in config"
+        )
+    if not resolved_token:
+        raise ConfigError("missing token: pass token=... or set RUNTA_TOKEN")
+    return resolved_endpoint, resolved_token
+
+
+def _read_config(config_path: str | Path | None) -> tuple[str | None, str | None]:
+    path = (
+        Path(config_path).expanduser()
+        if config_path is not None
+        else Path(os.getenv("RUNTA_CONFIG", "~/.config/runta/config.toml")).expanduser()
+    )
+    if not path.exists():
+        return None, None
+    try:
+        data = tomllib.loads(path.read_text())
+    except OSError as exc:
+        raise ConfigError(f"failed to read config file {path}: {exc}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"failed to parse config file {path}: {exc}") from exc
+    return _clean(data.get("endpoint")), _clean(data.get("token"))
+
+
+def _read_token_file(token_file: str | None) -> str | None:
+    token_file = _clean(token_file)
+    if token_file is None:
+        return None
+    path = Path(token_file).expanduser()
+    if not path.exists():
+        return None
+    try:
+        return _clean(path.read_text())
+    except OSError as exc:
+        raise ConfigError(f"failed to read token file {path}: {exc}") from exc
+
+
+def _clean(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    return value or None

asyncrunta/_http.py

@@ -0,0 +1,345 @@
+"""Low-level async REST client for runta-api."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import httpx
+
+from .errors import ApiError
+from .models import (
+    CommandResult,
+    EgressAuditEvent,
+    EgressPolicy,
+    RuntimeInfo,
+    SecretInfo,
+    SecretInjectionRuleInfo,
+    SnapshotInfo,
+)
+
+
+class HttpClient:
+    """Small typed wrapper around runta-api's HTTP/JSON surface."""
+
+    def __init__(self, endpoint: str, token: str, timeout: float = 30.0) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._runtime_base_path = "/v1/runtimes"
+        self._client = httpx.AsyncClient(
+            base_url=self.endpoint,
+            timeout=timeout,
+            trust_env=False,
+            headers={
+                "authorization": f"Bearer {token}",
+                "user-agent": "runta-python-sdk/0.1.0",
+            },
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        headers = {"x-request-id": str(uuid.uuid4())}
+        try:
+            response = await self._client.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                headers=headers,
+            )
+        except httpx.HTTPError as exc:
+            raise ApiError(f"HTTP request failed: {exc}") from exc
+        if response.status_code >= 400:
+            raise _api_error(response)
+        if not response.content:
+            return None
+        payload = response.json()
+        return payload.get("data", payload)
+
+    async def runtime_request(
+        self,
+        method: str,
+        suffix: str = "",
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        runtime_base_path = getattr(self, "_runtime_base_path", "/v1/runtimes")
+        path = f"{runtime_base_path}{suffix}"
+        try:
+            return await self.request(method, path, json=json, params=params)
+        except ApiError as exc:
+            if exc.status_code != 404 or runtime_base_path != "/v1/runtimes":
+                raise
+            legacy_path = f"/v1/sandboxes{suffix}"
+            data = await self.request(method, legacy_path, json=json, params=params)
+            self._runtime_base_path = "/v1/sandboxes"
+            return data
+
+    async def runtime_file_request(
+        self,
+        method: str,
+        runtime_id: str,
+        path: str,
+        *,
+        content: bytes | None = None,
+    ) -> httpx.Response:
+        headers = {"x-request-id": str(uuid.uuid4())}
+        if content is not None:
+            headers["content-type"] = "application/octet-stream"
+        runtime_base_path = getattr(self, "_runtime_base_path", "/v1/runtimes")
+        route = f"{runtime_base_path}/{runtime_id}/files"
+        try:
+            response = await self._client.request(
+                method,
+                route,
+                params={"path": path},
+                content=content,
+                headers=headers,
+            )
+        except httpx.HTTPError as exc:
+            raise ApiError(f"HTTP request failed: {exc}") from exc
+        if response.status_code == 404 and runtime_base_path == "/v1/runtimes":
+            legacy_route = f"/v1/sandboxes/{runtime_id}/files"
+            try:
+                response = await self._client.request(
+                    method,
+                    legacy_route,
+                    params={"path": path},
+                    content=content,
+                    headers=headers,
+                )
+            except httpx.HTTPError as exc:
+                raise ApiError(f"HTTP request failed: {exc}") from exc
+            if response.status_code < 400:
+                self._runtime_base_path = "/v1/sandboxes"
+        if response.status_code >= 400:
+            raise _api_error(response)
+        return response
+
+    async def health(self) -> Any:
+        return await self.request("GET", "/healthz")
+
+    async def create_runtime(
+        self,
+        name: str | None = None,
+        *,
+        snapshot_id: str | None = None,
+        vcpus: int = 1,
+        cur_memory_mib: int = 1024,
+        min_memory_mib: int = 0,
+        max_memory_mib: int = 0,
+        ingress_specs: Sequence[dict[str, Any]] | None = None,
+        arch: str | None = None,
+        egress_policy: EgressPolicy | None = None,
+        idle_suspend_after_secs: int | None = None,
+        **_ignored: Any,
+    ) -> RuntimeInfo:
+        body: dict[str, Any] = {
+            "name": name,
+            "snapshot_id": snapshot_id,
+            "vcpus": vcpus,
+            "cur_memory_mib": cur_memory_mib,
+            "min_memory_mib": min_memory_mib,
+            "max_memory_mib": max_memory_mib,
+            "ingress_specs": list(ingress_specs or []),
+            "egress_policy": egress_policy.to_json() if egress_policy else EgressPolicy().to_json(),
+            "idle_suspend_after_secs": idle_suspend_after_secs,
+        }
+        if arch is not None:
+            body["arch"] = arch
+        return RuntimeInfo.from_json(await self.runtime_request("POST", json=_drop_none(body)))
+
+    async def list_runtimes(self, status: str | None = None) -> list[RuntimeInfo]:
+        params = {"status": status} if status else None
+        data = await self.runtime_request("GET", params=params)
+        return [RuntimeInfo.from_json(item) for item in data]
+
+    async def get_runtime(self, runtime_id: str) -> RuntimeInfo:
+        return RuntimeInfo.from_json(await self.runtime_request("GET", f"/{runtime_id}"))
+
+    async def delete_runtime(self, runtime_id: str) -> None:
+        await self.runtime_request("DELETE", f"/{runtime_id}")
+
+    async def read_file(self, runtime_id: str, path: str) -> bytes:
+        response = await self.runtime_file_request("GET", runtime_id, path)
+        return response.content
+
+    async def write_file(self, runtime_id: str, path: str, content: bytes | str) -> None:
+        if isinstance(content, str):
+            content = content.encode()
+        await self.runtime_file_request("PUT", runtime_id, path, content=content)
+
+    async def update_runtime_status(self, runtime_id: str, action: str) -> RuntimeInfo:
+        path = {
+            "running": "start",
+            "active": "start",
+            "paused": "pause",
+            "pause": "pause",
+            "resume": "resume",
+            "shutdown": "stop",
+            "stopped": "stop",
+            "stop": "stop",
+        }[action]
+        return RuntimeInfo.from_json(await self.runtime_request("POST", f"/{runtime_id}/{path}"))
+
+    async def enable_egress(self, runtime_id: str) -> RuntimeInfo:
+        return RuntimeInfo.from_json(await self.runtime_request("POST", f"/{runtime_id}/egress/enable"))
+
+    async def disable_egress(self, runtime_id: str) -> RuntimeInfo:
+        return RuntimeInfo.from_json(await self.runtime_request("POST", f"/{runtime_id}/egress/disable"))
+
+    async def get_egress(self, runtime_id: str) -> dict[str, Any]:
+        return await self.runtime_request("GET", f"/{runtime_id}/egress")
+
+    async def list_egress_audit(self, runtime_id: str, limit: int = 100) -> list[EgressAuditEvent]:
+        data = await self.runtime_request(
+            "GET",
+            f"/{runtime_id}/egress/audit",
+            params={"limit": limit},
+        )
+        return [EgressAuditEvent.from_json(item) for item in data]
+
+    async def add_allowlist_hosts(self, runtime_id: str, hosts: Sequence[str]) -> dict[str, Any]:
+        return await self.runtime_request(
+            "PATCH",
+            f"/{runtime_id}/egress/allowlist",
+            json={"add": list(hosts)},
+        )
+
+    async def remove_allowlist_hosts(self, runtime_id: str, hosts: Sequence[str]) -> dict[str, Any]:
+        return await self.runtime_request(
+            "PATCH",
+            f"/{runtime_id}/egress/allowlist",
+            json={"remove": list(hosts)},
+        )
+
+    async def execute(
+        self,
+        runtime_id: str,
+        command: str,
+        args: Sequence[str] = (),
+        *,
+        env: Mapping[str, str] | None = None,
+        stdin: bytes | str | None = None,
+        timeout: float | None = None,
+        cwd: str | None = None,
+        max_output_bytes: int | None = None,
+    ) -> CommandResult:
+        started = time.monotonic()
+        if isinstance(stdin, bytes):
+            stdin = stdin.decode(errors="replace")
+        body = {
+            "command": command,
+            "args": list(args),
+            "timeout_secs": int(timeout) if timeout is not None else None,
+            "env": dict(env) if env else None,
+            "stdin": stdin,
+            "cwd": cwd,
+            "max_output_bytes": max_output_bytes,
+        }
+        data = await self.runtime_request("POST", f"/{runtime_id}/exec", json=_drop_none(body))
+        return CommandResult(
+            exit_code=int(data["exit_code"]),
+            stdout=str(data.get("stdout", "")).encode(),
+            stderr=str(data.get("stderr", "")).encode(),
+            duration=float(data.get("duration_ms", 0)) / 1000.0 or time.monotonic() - started,
+            stdout_truncated=bool(data.get("stdout_truncated", False)),
+            stderr_truncated=bool(data.get("stderr_truncated", False)),
+        )
+
+    async def create_secret(self, name: str, value: str, cache_ttl_secs: int = 0) -> SecretInfo:
+        data = await self.request(
+            "POST",
+            "/v1/secrets",
+            json={"name": name, "value": value, "cache_ttl_secs": cache_ttl_secs},
+        )
+        return SecretInfo.from_json(data)
+
+    async def list_secrets(self) -> list[SecretInfo]:
+        return [SecretInfo.from_json(item) for item in await self.request("GET", "/v1/secrets")]
+
+    async def get_secret(self, secret_id: str) -> SecretInfo:
+        return SecretInfo.from_json(await self.request("GET", f"/v1/secrets/{secret_id}"))
+
+    async def delete_secret(self, secret_id: str) -> None:
+        await self.request("DELETE", f"/v1/secrets/{secret_id}")
+
+    async def create_secret_injection_rule(
+        self,
+        runtime_id: str,
+        host: str,
+        path: str | None,
+        secret: str,
+        injection: Mapping[str, Any],
+    ) -> SecretInjectionRuleInfo:
+        data = await self.runtime_request(
+            "POST",
+            f"/{runtime_id}/secret-injection-rules",
+            json=_drop_none({"host": host, "path": path, "secret": secret, "injection": dict(injection)}),
+        )
+        return SecretInjectionRuleInfo.from_json(data)
+
+    async def list_secret_injection_rules(self, runtime_id: str) -> list[SecretInjectionRuleInfo]:
+        data = await self.runtime_request("GET", f"/{runtime_id}/secret-injection-rules")
+        return [SecretInjectionRuleInfo.from_json(item) for item in data]
+
+    async def get_secret_injection_rule(self, runtime_id: str, rule_id: str) -> SecretInjectionRuleInfo:
+        data = await self.runtime_request("GET", f"/{runtime_id}/secret-injection-rules/{rule_id}")
+        return SecretInjectionRuleInfo.from_json(data)
+
+    async def delete_secret_injection_rule(self, runtime_id: str, rule_id: str) -> None:
+        await self.runtime_request("DELETE", f"/{runtime_id}/secret-injection-rules/{rule_id}")
+
+    create_secret_rule = create_secret_injection_rule
+    list_secret_rules = list_secret_injection_rules
+    get_secret_rule = get_secret_injection_rule
+    delete_secret_rule = delete_secret_injection_rule
+
+    async def create_snapshot(self, runtime_id: str, name: str | None = None, kind: str = "full") -> SnapshotInfo:
+        data = await self.runtime_request(
+            "POST",
+            f"/{runtime_id}/snapshots",
+            json=_drop_none({"name": name, "kind": kind}),
+        )
+        return SnapshotInfo.from_json(data)
+
+    async def list_snapshots(self) -> list[SnapshotInfo]:
+        return [SnapshotInfo.from_json(item) for item in await self.request("GET", "/v1/snapshots")]
+
+    async def get_snapshot(self, snapshot_id: str) -> SnapshotInfo:
+        return SnapshotInfo.from_json(await self.request("GET", f"/v1/snapshots/{snapshot_id}"))
+
+    async def delete_snapshot(self, snapshot_id: str) -> None:
+        await self.request("DELETE", f"/v1/snapshots/{snapshot_id}")
+
+
+def _api_error(response: httpx.Response) -> ApiError:
+    code = None
+    request = response.request
+    message = response.text.strip()
+    try:
+        body = response.json().get("error", {})
+        code = body.get("code")
+        message = body.get("message") or message
+    except ValueError:
+        pass
+    if not message:
+        message = f"{request.method} {request.url.path} failed"
+    return ApiError(message, status_code=response.status_code, code=code)
+
+
+def _drop_none(data: Mapping[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in data.items() if value is not None}