solari-core 0.2.0__tar.gz

solari_core-0.2.0/.gitignore

@@ -0,0 +1,71 @@
+# build artifacts
+dist/
+**/dist/
+**/node_modules/
+**/target/
+*.log
+
+# VM images / snapshots / kernels — large binaries, never committed
+*.img
+*.ext4
+*.qcow2
+*.raw
+*.snapshot
+/snapshots/build/
+/guest/rootfs/build/
+/guest/kernel/build/
+vmlinux
+bzImage
+
+# terraform state
+*.tfstate
+*.tfstate.*
+.terraform/
+*.tfvars.local
+
+# secrets / env
+.env
+.env.*
+*.pem
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# NOTE: tests/sdk/ts-request-fixtures.json is deliberately NOT ignored.
+#
+# It was, and that quietly disabled two gates at once:
+#
+#  1. ci.yml's "Committed fixture must match what the SDK emits today" step runs
+#     `git diff --exit-code tests/sdk/ts-request-fixtures.json`. On an ignored,
+#     never-tracked file that command can only ever succeed — it had never once
+#     been able to fail.
+#  2. The Go/Rust/C++/Python contract suites now assert against that fixture from
+#     inside their OWN CI jobs, none of which run the TypeScript half. If the file
+#     is not committed, it is simply absent there.
+#
+# It is generated, but it is generated from the REFERENCE SDK and checked in as
+# the baseline the other four bindings are held to — regenerating it and diffing
+# is exactly how a wire change is made to announce itself.
+
+# Built guest-agent binaries (produced by go build / build-rootfs staging)
+guest/agent/agent
+guest/rootfs/guest-agent
+
+# build-rootfs.sh template staging + generated Dockerfile (regenerated each run)
+guest/rootfs/guest-agent.service
+guest/rootfs/template.packages
+guest/rootfs/template-files/
+guest/rootfs/.Dockerfile.gen
+guest/rootfs/out/
+
+# local test artifacts
+staging-desktop.png
+desktop.png
+infra/terraform/snapshots-volumes/.build/
+
+# deploy-e2e scratch state: holds a presigned REPO_URL with live STS creds
+# (ASIA... + X-Amz-Security-Token). Never commit. Also stale PHASE_* here makes
+# a bare re-run skip bake+verify and exit 0 with zero assertions.
+infra/.deploy-e2e/

solari_core-0.2.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: solari-core
+Version: 0.2.0
+Summary: Shared runtime for the Solari VM SDKs (transport, session handles, image builder, types).
+Project-URL: Homepage, https://getsolari.com
+Author: Solari
+License: MIT
+Keywords: desktop,microvm,sandbox,solari
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: websockets>=11.0
+Description-Content-Type: text/markdown
+
+# solari-core
+
+Shared runtime for the Solari VM SDKs — the HTTP/WebSocket transport, the
+`Desktop` and `Sandbox` session handles, the image builder, and the typed error
+hierarchy. Mirrors the TypeScript `@solarisdk/core` package.
+
+You normally install a leaf package instead:
+
+- [`solari-desktop`](https://pypi.org/project/solari-desktop/) — computer-use desktops
+- [`solari-sandbox`](https://pypi.org/project/solari-sandbox/) — code sandboxes
+
+Both depend on and re-export `solari-core`, so `SandboxClient` / `DesktopClient`
+plus the shared types are importable straight from the leaf package.
+
+Docs: <https://getsolari.com>

solari_core-0.2.0/README.md

@@ -0,0 +1,15 @@
+# solari-core
+
+Shared runtime for the Solari VM SDKs — the HTTP/WebSocket transport, the
+`Desktop` and `Sandbox` session handles, the image builder, and the typed error
+hierarchy. Mirrors the TypeScript `@solarisdk/core` package.
+
+You normally install a leaf package instead:
+
+- [`solari-desktop`](https://pypi.org/project/solari-desktop/) — computer-use desktops
+- [`solari-sandbox`](https://pypi.org/project/solari-sandbox/) — code sandboxes
+
+Both depend on and re-export `solari-core`, so `SandboxClient` / `DesktopClient`
+plus the shared types are importable straight from the leaf package.
+
+Docs: <https://getsolari.com>

solari_core-0.2.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "solari-core"
+version = "0.2.0"
+description = "Shared runtime for the Solari VM SDKs (transport, session handles, image builder, types)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Solari" }]
+keywords = ["solari", "sandbox", "desktop", "microvm"]
+dependencies = ["httpx>=0.24", "websockets>=11.0"]
+
+[project.urls]
+Homepage = "https://getsolari.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["solari_core"]

solari_core-0.2.0/solari_core/__init__.py

@@ -0,0 +1,51 @@
+"""solari_core — shared runtime for the Solari VM SDKs.
+
+The transport, session handles (:class:`Desktop`, :class:`Sandbox`), image
+builder, and typed errors shared by ``solari-desktop`` and ``solari-sandbox``.
+Mirrors the TypeScript ``@solarisdk/core`` package. You normally install one of
+the leaf packages (``solari-desktop`` / ``solari-sandbox``), which re-export
+this surface; import from here directly only for shared types.
+"""
+from __future__ import annotations
+
+from ._http import HttpTransport, new_idempotency_key
+from .desktop import Desktop, DesktopConfig, ExecStreamHandler
+from .handle import SessionConfig, SessionHandle, SessionHooks
+from .image import CompiledImage, Image, LocalCopy
+from .sandbox import Sandbox
+from .template_client import SyncTemplateClient, TemplateClient
+from .volume_client import SyncVolumeClient, VolumeClient
+from .errors import (
+    ActionError, AuthError, ConcurrencyLimitError, ConnectionError,
+    GatewayError, NoCapacityError, SolariError, PlanError, TimeoutError,
+)
+from .types import (
+    CodeLanguage, CodeResultItem, CommandResult, CreateDesktopResponse,
+    CreateSandboxResponse, DeleteDesktopResponse, DesktopLifecycleResponse,
+    DesktopStatus, ExecResult, ExecStreamChunk, FsEntry, FsSearchMatch, FsStat,
+    FsWatchEvent, GatewayErrorBody, GitBranch, GitCommit, GitStatus,
+    GetDesktopResponse, HealthResult, KeyAction, MetricsResult, MouseAction,
+    MouseButton, PackageManager, PkgInstallResult, PortInfo, ProcessInfo,
+    RpcErrorBody, RpcResponse, RunCodeResult, SandboxKind, SandboxState,
+    SandboxView, ScreenshotFormat, SnapshotView,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "HttpTransport", "new_idempotency_key",
+    "Image", "CompiledImage", "LocalCopy",
+    "TemplateClient", "SyncTemplateClient", "VolumeClient", "SyncVolumeClient",
+    "Desktop", "DesktopConfig", "ExecStreamHandler", "Sandbox",
+    "SessionHandle", "SessionConfig", "SessionHooks",
+    "ActionError", "AuthError", "ConcurrencyLimitError", "ConnectionError",
+    "GatewayError", "NoCapacityError", "SolariError", "PlanError", "TimeoutError",
+    "CreateDesktopResponse", "CreateSandboxResponse", "DeleteDesktopResponse",
+    "DesktopLifecycleResponse", "DesktopStatus", "ExecResult", "ExecStreamChunk",
+    "FsEntry", "FsStat", "GatewayErrorBody", "GetDesktopResponse", "HealthResult",
+    "KeyAction", "MouseAction", "MouseButton", "PackageManager", "PkgInstallResult",
+    "PortInfo", "ProcessInfo", "RpcErrorBody", "RpcResponse", "ScreenshotFormat",
+    "CodeLanguage", "CodeResultItem", "CommandResult", "FsSearchMatch",
+    "FsWatchEvent", "GitBranch", "GitCommit", "GitStatus", "MetricsResult",
+    "RunCodeResult", "SandboxKind", "SandboxState", "SandboxView", "SnapshotView",
+]

solari_core-0.2.0/solari_core/_http.py

@@ -0,0 +1,142 @@
+"""Shared async HTTP transport (mirrors the TypeScript ``src/http.ts``).
+
+Both :class:`DesktopClient` and :class:`SandboxClient` delegate here so there is
+ONE place owning auth headers, error mapping, retries/backoff, idempotency keys,
+and timeouts.
+
+Retry policy: idempotent requests (GET, DELETE, or any carrying an
+Idempotency-Key) are retried on network errors, HTTP 5xx, and bodies flagged
+``retryable``, with exponential backoff + jitter. Non-idempotent writes are
+never silently retried — pass ``idempotency_key`` to opt a create into safe
+retries. 429 is NOT retried (it is our ConcurrencyLimitError).
+"""
+from __future__ import annotations
+
+import asyncio
+import random
+import uuid
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import ConnectionError as PtConnectionError
+from .errors import SolariError, map_gateway_error
+from .types import GatewayErrorBody
+
+
+def new_idempotency_key() -> str:
+    """A fresh idempotency key (UUID)."""
+    return str(uuid.uuid4())
+
+
+class HttpTransport:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        http: Optional[httpx.AsyncClient] = None,
+        max_retries: int = 5,
+        request_timeout_ms: int = 300_000,
+        retry_delay_ms: Optional[int] = None,
+    ) -> None:
+        if not api_key:
+            raise SolariError("HttpTransport requires an api_key")
+        if not base_url:
+            raise SolariError("HttpTransport requires a base_url")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._http = http
+        self._owns_http = http is None
+        self._max_retries = max_retries
+        self._timeout = request_timeout_ms / 1000.0
+        self._retry_delay_ms = retry_delay_ms
+
+    def _client(self) -> httpx.AsyncClient:
+        if self._http is None:
+            self._http = httpx.AsyncClient()
+        return self._http
+
+    def auth_headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    def ws_origin(self) -> str:
+        if self._base_url.startswith("https"):
+            return "wss" + self._base_url[len("https"):]
+        if self._base_url.startswith("http"):
+            return "ws" + self._base_url[len("http"):]
+        return self._base_url
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Any] = None,
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        idempotent = method in ("GET", "DELETE") or idempotency_key is not None
+        headers: Dict[str, str] = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        attempt = 0
+        while True:
+            try:
+                res = await self._client().request(
+                    method,
+                    f"{self._base_url}{path}",
+                    headers=headers,
+                    json=body if body is not None else None,
+                    timeout=self._timeout,
+                )
+            except httpx.HTTPError as exc:
+                if idempotent and attempt < self._max_retries:
+                    await asyncio.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise PtConnectionError(f"{method} {path} failed: {exc}") from exc
+
+            if res.is_error:
+                err_body: Optional[GatewayErrorBody] = None
+                try:
+                    parsed = res.json()
+                    if isinstance(parsed, dict):
+                        err_body = GatewayErrorBody(
+                            code=parsed.get("code"),
+                            error=parsed.get("error"),
+                            message=parsed.get("message"),
+                            retryable=parsed.get("retryable"),
+                        )
+                except Exception:  # noqa: BLE001 - body may be empty/non-JSON
+                    err_body = None
+                # 5xx or explicit retryable hint; NOT 429 (ConcurrencyLimitError).
+                retryable = res.status_code >= 500 or (
+                    err_body is not None and err_body.retryable is True
+                )
+                if idempotent and retryable and attempt < self._max_retries:
+                    await asyncio.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise map_gateway_error(res.status_code, err_body)
+
+            if not res.content:
+                return None
+            return res.json()
+
+    def _backoff(self, attempt: int) -> float:
+        if self._retry_delay_ms is not None:
+            return self._retry_delay_ms / 1000.0
+        # Base 150ms (was 1000): a create bounced by a transient host no_capacity
+        # during a burst re-picks a different host in ~150ms, not a full second.
+        return min(0.15 * 2 ** attempt, 8.0) + random.random() * 0.25
+
+    async def aclose(self) -> None:
+        if self._owns_http and self._http is not None:
+            await self._http.aclose()
+            self._http = None