drukbox-python-sdk 0.3.0__tar.gz → 0.5.0__tar.gz

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: drukbox-python-sdk
-Version: 0.3.0
+Version: 0.5.0
 Summary: Async Python client for Drukbox.
 Project-URL: Homepage, https://github.com/clawhaven/drukbox-python-sdk
 Project-URL: Repository, https://github.com/clawhaven/drukbox-python-sdk
@@ -59,6 +59,8 @@ finally:
 few minutes worst case. The SDK's default `timeout` (300s) covers this. Pass
 an `idempotency_key` for retry safety: a retry with the same key after a
 successful provision returns the original host instead of creating a duplicate.
+A provider at its host limit raises `SandboxCapacityError`, a
+`SandboxUnavailableError` whose `retry_after` gives the seconds to wait.
 
 `SandboxAPI.from_env(prefix="SANDBOX_")` reads
 `SANDBOX_SERVICE_URL`, `SANDBOX_SERVICE_TOKEN`, and optional

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.5.0}/README.md

@@ -46,6 +46,8 @@ finally:
 few minutes worst case. The SDK's default `timeout` (300s) covers this. Pass
 an `idempotency_key` for retry safety: a retry with the same key after a
 successful provision returns the original host instead of creating a duplicate.
+A provider at its host limit raises `SandboxCapacityError`, a
+`SandboxUnavailableError` whose `retry_after` gives the seconds to wait.
 
 `SandboxAPI.from_env(prefix="SANDBOX_")` reads
 `SANDBOX_SERVICE_URL`, `SANDBOX_SERVICE_TOKEN`, and optional

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "drukbox-python-sdk"
-version = "0.3.0"
+version = "0.5.0"
 description = "Async Python client for Drukbox."
 readme = "README.md"
 license = "MIT"

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.5.0}/src/drukbox_sdk/__init__.py

@@ -19,6 +19,7 @@ from .api import (
 from .exceptions import (
     SandboxAPIError,
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -36,6 +37,7 @@ __all__ = [
     "SandboxAPI",
     "SandboxAPIError",
     "SandboxAuthError",
+    "SandboxCapacityError",
     "SandboxConflictError",
     "SandboxHost",
     "SandboxNotFoundError",

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.5.0}/src/drukbox_sdk/api.py

@@ -47,6 +47,7 @@ import httpx
 
 from .exceptions import (
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -197,7 +198,8 @@ class DoctorReport:
 
     ok: bool
     active_provider: str
-    tailscale_enabled: bool
+    # Whether the active provider's hosts join the tailnet.
+    tailnet: bool
     checks: list[DoctorCheck]
 
 
@@ -435,14 +437,15 @@ class SandboxAPI:
         base_image: str | None = None,
         label: str | None = None,
     ) -> SandboxTemplate:
-        """Start a template build and return immediately.
-
-        The service responds 202 with ``status="building"``. Poll
-        :meth:`get_template` until the status becomes ``"available"`` or
-        ``"failed"``. A failed record carries the reason in
-        ``last_error``. A repeated post with the same provider, base
-        image, and setup script returns the existing record without a
-        rebuild.
+        """Start a template build.
+
+        The service pulls the base image, then responds 202 with
+        ``status="building"``. Poll :meth:`get_template` until the status
+        becomes ``"available"`` or ``"failed"``. A failed record carries the
+        reason in ``last_error``. A repeated post with the same provider,
+        base image digest, and setup script returns the existing record. A
+        ``"failed"`` record builds again and keeps its ``last_error`` until
+        that build ends.
         """
 
         payload: dict[str, Any] = {"setup_script": setup_script}
@@ -488,7 +491,8 @@ class SandboxAPI:
         return DoctorReport(
             ok=data["ok"],
             active_provider=data["active_provider"],
-            tailscale_enabled=data["tailscale_enabled"],
+            # drukbox before "Join the tailnet per provider" sent tailscale_enabled.
+            tailnet=data["tailnet"] if "tailnet" in data else data["tailscale_enabled"],
             checks=[DoctorCheck(**check) for check in data["checks"]],
         )
 
@@ -614,6 +618,11 @@ class SandboxAPI:
             raise SandboxProvisioningError(json_response.get("detail", "provisioning failed"))
 
         if response.status_code == 503:
+            if json_response.get("error_code") == "CAPACITY":
+                raise SandboxCapacityError(
+                    json_response.get("detail", "provider at host limit"),
+                    retry_after=int(response.headers["Retry-After"]),
+                )
             raise SandboxUnavailableError(json_response.get("detail", "service unavailable"))
 
         if response.status_code == 422:

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.5.0}/src/drukbox_sdk/exceptions.py

@@ -18,6 +18,18 @@ class SandboxUnavailableError(RuntimeError):
     """
 
 
+class SandboxCapacityError(SandboxUnavailableError):
+    """503 — the provider is at its host limit.
+
+    ``retry_after`` is the service's ``Retry-After`` value in seconds:
+    wait at least that long before the next create.
+    """
+
+    def __init__(self, message: str, retry_after: int) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
 class SandboxAPIError(RuntimeError):
     """Base for any error the sandbox service returned via HTTP."""
 

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.5.0}/tests/test_api.py

@@ -28,6 +28,7 @@ from drukbox_sdk import (
     Issuer,
     SandboxAPI,
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -47,7 +48,7 @@ def _doctor_payload(**overrides: Any) -> dict[str, Any]:
     payload: dict[str, Any] = {
         "ok": True,
         "active_provider": "aws",
-        "tailscale_enabled": True,
+        "tailnet": True,
         "checks": [
             {
                 "name": "db",
@@ -796,6 +797,27 @@ async def test_503_raises_sandbox_unavailable_error(api: SandboxAPI):
         await api.list_hosts()
 
 
+@respx.mock
+async def test_capacity_503_raises_sandbox_capacity_error(api: SandboxAPI):
+    """A 503 with error_code CAPACITY is a host-limit refusal, not an
+    outage. It stays a SandboxUnavailableError so existing retries keep
+    working, and carries the service's Retry-After in seconds."""
+
+    respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(
+            503,
+            json={"detail": "provider 'exe' is at its host limit", "error_code": "CAPACITY"},
+            headers={"Retry-After": "30"},
+        ),
+    )
+
+    with pytest.raises(SandboxCapacityError, match="host limit") as exc_info:
+        await api.create_host()
+
+    assert isinstance(exc_info.value, SandboxUnavailableError)
+    assert exc_info.value.retry_after == 30
+
+
 @respx.mock
 async def test_non_json_body_raises_sandbox_response_error(api: SandboxAPI):
     respx.get(f"{BASE_URL}/hosts").mock(
@@ -903,6 +925,17 @@ def test_from_env_strips_trailing_slash_via_constructor(
     assert sandbox.base_url == "https://trailing.test"
 
 
+@respx.mock
+async def test_doctor_reads_tailscale_enabled_from_an_older_drukbox(api: SandboxAPI):
+    payload = _doctor_payload()
+    payload["tailscale_enabled"] = payload.pop("tailnet")
+    respx.get(f"{BASE_URL}/doctor").mock(return_value=httpx.Response(200, json=payload))
+
+    report = await api.doctor()
+
+    assert report.tailnet is True
+
+
 @respx.mock
 async def test_doctor_parses_report_and_checks(api: SandboxAPI):
     route = respx.get(f"{BASE_URL}/doctor").mock(
@@ -915,7 +948,7 @@ async def test_doctor_parses_report_and_checks(api: SandboxAPI):
     assert route.calls.last.request.headers["Authorization"] == "Bearer t-test"
     assert report.ok is True
     assert report.active_provider == "aws"
-    assert report.tailscale_enabled is True
+    assert report.tailnet 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"