drukbox-python-sdk 0.0.3__tar.gz → 0.0.5__tar.gz

{drukbox_python_sdk-0.0.3 → drukbox_python_sdk-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drukbox-python-sdk
-Version: 0.0.3
+Version: 0.0.5
 Summary: Async Python client for Drukbox.
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.28
@@ -65,6 +65,7 @@ Public exports live in `drukbox_sdk`:
 
 - `SandboxAPI`
 - `SandboxHost`
+- `DoctorReport` and `DoctorCheck`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
   unavailable, and unclassified response errors
 
@@ -75,10 +76,17 @@ Supported host operations:
 - `attach`
 - `list_hosts`
 - `delete_host`
+- `doctor`
 - `aclose`
 
 `create_host` supports the service's optional `image`, `env`, `expires_at`,
-and `Idempotency-Key` inputs.
+`provider`, and `Idempotency-Key` inputs.
+
+`doctor` fetches `GET /doctor` — read-only dependency health. The service
+runs one cheap, non-mutating probe per dependency (database, active VM
+provider, Tailscale when enabled) and always responds 200, so callers branch
+on `DoctorReport.ok` rather than the HTTP status. A failed `DoctorCheck`
+carries a stable `hint` slug for remediation.
 
 The SDK does not mint Tailscale auth keys, manage ACLs, establish SSH,
 provision Linux users, transfer files, or run remote commands.

{drukbox_python_sdk-0.0.3 → drukbox_python_sdk-0.0.5}/README.md

@@ -57,6 +57,7 @@ Public exports live in `drukbox_sdk`:
 
 - `SandboxAPI`
 - `SandboxHost`
+- `DoctorReport` and `DoctorCheck`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
   unavailable, and unclassified response errors
 
@@ -67,10 +68,17 @@ Supported host operations:
 - `attach`
 - `list_hosts`
 - `delete_host`
+- `doctor`
 - `aclose`
 
 `create_host` supports the service's optional `image`, `env`, `expires_at`,
-and `Idempotency-Key` inputs.
+`provider`, and `Idempotency-Key` inputs.
+
+`doctor` fetches `GET /doctor` — read-only dependency health. The service
+runs one cheap, non-mutating probe per dependency (database, active VM
+provider, Tailscale when enabled) and always responds 200, so callers branch
+on `DoctorReport.ok` rather than the HTTP status. A failed `DoctorCheck`
+carries a stable `hint` slug for remediation.
 
 The SDK does not mint Tailscale auth keys, manage ACLs, establish SSH,
 provision Linux users, transfer files, or run remote commands.

{drukbox_python_sdk-0.0.3 → drukbox_python_sdk-0.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "drukbox-python-sdk"
-version = "0.0.3"
+version = "0.0.5"
 description = "Async Python client for Drukbox."
 readme = "README.md"
 # Tracks the lowest Python any current consumer supports. Bump only

{drukbox_python_sdk-0.0.3 → drukbox_python_sdk-0.0.5}/src/drukbox_sdk/__init__.py

@@ -5,6 +5,8 @@ detail and may change without notice.
 """
 
 from .api import (
+    DoctorCheck,
+    DoctorReport,
     SandboxAPI,
     SandboxHost,
 )
@@ -19,6 +21,8 @@ from .exceptions import (
 )
 
 __all__ = [
+    "DoctorCheck",
+    "DoctorReport",
     "SandboxAPI",
     "SandboxAPIError",
     "SandboxAuthError",

{drukbox_python_sdk-0.0.3 → drukbox_python_sdk-0.0.5}/src/drukbox_sdk/api.py

@@ -112,6 +112,46 @@ def _parse_sandbox_host(data: dict[str, Any]) -> SandboxHost:
     return SandboxHost(**{key: data[key] for key in _SANDBOX_HOST_FIELDS})
 
 
+@dataclass(frozen=True)
+class DoctorCheck:
+    """One dependency probe. ``hint`` is a remediation slug, set only on failures."""
+
+    name: str
+    status: str
+    detail: str | None
+    latency_ms: int | None
+    hint: str | None
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    """Health snapshot. The HTTP status is always 200 — branch on ``ok``."""
+
+    ok: bool
+    active_provider: str
+    tailscale_enabled: bool
+    checks: list[DoctorCheck]
+
+
+def _parse_doctor_check(data: dict[str, Any]) -> DoctorCheck:
+    return DoctorCheck(
+        name=data["name"],
+        status=data["status"],
+        detail=data["detail"],
+        latency_ms=data["latency_ms"],
+        hint=data["hint"],
+    )
+
+
+def _parse_doctor_report(data: dict[str, Any]) -> DoctorReport:
+    return DoctorReport(
+        ok=data["ok"],
+        active_provider=data["active_provider"],
+        tailscale_enabled=data["tailscale_enabled"],
+        checks=[_parse_doctor_check(check) for check in data["checks"]],
+    )
+
+
 class SandboxAPI:
     """Async client for Drukbox.
 
@@ -174,6 +214,7 @@ class SandboxAPI:
         expires_at: datetime | None = None,
         idempotency_key: str | None = None,
         image: str | None = None,
+        provider: str | None = None,
     ) -> SandboxHost:
         """Provision a new host.
 
@@ -188,6 +229,10 @@ class SandboxAPI:
         header. Useful for retry safety on flaky networks — a retry with
         the same key after a successful provision returns the original
         host instead of creating a duplicate.
+
+        ``provider`` pins which VM provider serves the request; omit it to
+        use the service default. An unknown provider raises
+        :class:`SandboxResponseError` (the service rejects it with 400).
         """
 
         payload: dict[str, Any] = {}
@@ -197,6 +242,8 @@ class SandboxAPI:
             payload["expires_at"] = expires_at.isoformat()
         if image is not None:
             payload["image"] = image
+        if provider is not None:
+            payload["provider"] = provider
 
         headers: dict[str, str] = {}
         if idempotency_key is not None:
@@ -231,6 +278,17 @@ class SandboxAPI:
     async def delete_host(self, host_id: uuid.UUID | str) -> None:
         await self._request("DELETE", f"/hosts/{host_id}")
 
+    async def doctor(self) -> DoctorReport:
+        """Fetch ``GET /doctor`` — read-only dependency health.
+
+        Always responds 200; inspect :attr:`DoctorReport.ok`, not the HTTP
+        status. Auth failures raise :class:`SandboxAuthError`.
+        """
+
+        data = await self._request("GET", "/doctor")
+        assert isinstance(data, dict)
+        return _parse_doctor_report(data)
+
     async def aclose(self) -> None:
         if self._client is None:
             return

{drukbox_python_sdk-0.0.3 → drukbox_python_sdk-0.0.5}/tests/test_api.py

@@ -22,6 +22,7 @@ import pytest
 import respx
 
 from drukbox_sdk import (
+    DoctorReport,
     SandboxAPI,
     SandboxAuthError,
     SandboxConflictError,
@@ -35,6 +36,41 @@ from drukbox_sdk import (
 BASE_URL = "https://sandbox.test"
 
 
+def _doctor_payload(**overrides: Any) -> dict[str, Any]:
+    """One canonical /doctor payload used across tests; overrides per case."""
+
+    payload: dict[str, Any] = {
+        "ok": True,
+        "active_provider": "aws",
+        "tailscale_enabled": True,
+        "checks": [
+            {
+                "name": "db",
+                "status": "ok",
+                "detail": "select 1 -> 1",
+                "latency_ms": 2,
+                "hint": None,
+            },
+            {
+                "name": "provider",
+                "status": "ok",
+                "detail": "account=111122223333 arn=arn:aws:iam::111122223333:user/drukbox",
+                "latency_ms": 142,
+                "hint": None,
+            },
+            {
+                "name": "tailscale",
+                "status": "ok",
+                "detail": "tailnet=example.ts.net devices=3",
+                "latency_ms": 88,
+                "hint": None,
+            },
+        ],
+    }
+    payload.update(overrides)
+    return payload
+
+
 def _host_payload(**overrides: Any) -> dict[str, Any]:
     """One canonical host payload used across tests; overrides per case."""
 
@@ -128,9 +164,23 @@ async def test_create_host_omits_image_and_env_when_unset(api: SandboxAPI):
     assert "image" not in body
     assert "env" not in body
     assert "expires_at" not in body
+    assert "provider" not in body
     assert "Idempotency-Key" not in route.calls.last.request.headers
 
 
+@respx.mock
+async def test_create_host_sends_provider_when_set(api: SandboxAPI):
+    payload = _host_payload(provider="hetzner")
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=payload),
+    )
+
+    host = await api.create_host(provider="hetzner")
+
+    assert '"provider":"hetzner"' in route.calls.last.request.content.decode()
+    assert host.provider == "hetzner"
+
+
 @respx.mock
 async def test_get_host_returns_parsed_host(api: SandboxAPI):
     payload = _host_payload(status="active")
@@ -451,3 +501,95 @@ def test_from_env_strips_trailing_slash_via_constructor(
     sandbox = SandboxAPI.from_env()
 
     assert sandbox.base_url == "https://trailing.test"
+
+
+@respx.mock
+async def test_doctor_parses_report_and_checks(api: SandboxAPI):
+    route = respx.get(f"{BASE_URL}/doctor").mock(
+        return_value=httpx.Response(200, json=_doctor_payload()),
+    )
+
+    report = await api.doctor()
+
+    assert route.called
+    assert route.calls.last.request.headers["Authorization"] == "Bearer t-test"
+    assert isinstance(report, DoctorReport)
+    assert report.ok is True
+    assert report.active_provider == "aws"
+    assert report.tailscale_enabled is True
+    assert [check.name for check in report.checks] == ["db", "provider", "tailscale"]
+    provider = next(check for check in report.checks if check.name == "provider")
+    assert provider.status == "ok"
+    assert provider.latency_ms == 142
+    assert provider.hint is None
+
+
+@respx.mock
+async def test_doctor_surfaces_failure_with_hint(api: SandboxAPI):
+    """A failed probe round-trips status, detail, and the remediation hint;
+    the HTTP status is still 200, so callers branch on report.ok."""
+
+    payload = _doctor_payload(
+        ok=False,
+        checks=[
+            {
+                "name": "db",
+                "status": "ok",
+                "detail": "select 1 -> 1",
+                "latency_ms": 2,
+                "hint": None,
+            },
+            {
+                "name": "tailscale",
+                "status": "fail",
+                "detail": "Tailscale API authentication failed",
+                "latency_ms": 380,
+                "hint": "check_tailscale_oauth_and_api_reachability",
+            },
+        ],
+    )
+    respx.get(f"{BASE_URL}/doctor").mock(return_value=httpx.Response(200, json=payload))
+
+    report = await api.doctor()
+
+    assert report.ok is False
+    failed = next(check for check in report.checks if check.status == "fail")
+    assert failed.name == "tailscale"
+    assert failed.detail == "Tailscale API authentication failed"
+    assert failed.hint == "check_tailscale_oauth_and_api_reachability"
+
+
+@respx.mock
+async def test_doctor_ignores_unknown_check_fields(api: SandboxAPI):
+    """A future service adding a field to a check must not break today's SDK."""
+
+    payload = _doctor_payload(
+        checks=[
+            {
+                "name": "db",
+                "status": "ok",
+                "detail": "select 1 -> 1",
+                "latency_ms": 2,
+                "hint": None,
+                "future_field": "surprise",
+            },
+        ],
+    )
+    respx.get(f"{BASE_URL}/doctor").mock(return_value=httpx.Response(200, json=payload))
+
+    report = await api.doctor()
+
+    assert report.checks[0].name == "db"
+    assert not hasattr(report.checks[0], "future_field")
+
+
+@respx.mock
+async def test_doctor_401_raises_sandbox_auth_error(api: SandboxAPI):
+    """Doctor is service-token only; a bad token raises like every other call."""
+
+    respx.get(f"{BASE_URL}/doctor").mock(
+        return_value=httpx.Response(401, json={"detail": "service token required"}),
+    )
+
+    with pytest.raises(SandboxAuthError, match="service token required"):
+        await api.doctor()