drukbox-python-sdk 0.2.0__tar.gz → 0.4.0__tar.gz

{drukbox_python_sdk-0.2.0 → drukbox_python_sdk-0.4.0}/AGENTS.md

@@ -57,3 +57,6 @@ run.
   consumers unless the user asks for them.
 - Preserve user changes in the worktree; do not clean or rewrite unrelated
   files.
+- A version bump rides alone: one commit (`chore: bump to X`) that touches
+  only `pyproject.toml`, with no other change in it. Never fold the bump into
+  a feature or fix commit. The release tag is cut from the bump commit.

{drukbox_python_sdk-0.2.0 → drukbox_python_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: drukbox-python-sdk
-Version: 0.2.0
+Version: 0.4.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
@@ -73,6 +75,7 @@ Public exports live in `drukbox_sdk`:
 - `SandboxTemplate`
 - `Secret`
 - `Issuer`
+- `ServiceAccount`
 - `DoctorReport` and `DoctorCheck`
 - `HTTPProxy` and `HTTPProxyAttachment`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
@@ -86,6 +89,7 @@ Supported host operations:
 - `list_hosts`
 - `renew_host`
 - `delete_host`
+- `refresh_secret`
 - `doctor`
 - `aclose`
 
@@ -127,6 +131,24 @@ The response carries no secret. A service name Drukbox does not know raises
 `expires_at` to extend by the service's default TTL; renewal never makes a host
 permanent.
 
+`SandboxHost.service_account` names the service account that created or
+claimed the host, `admin` for an admin key, or `None` for an unclaimed warm
+host.
+
+`refresh_secret` makes the service forget the current value of one secret on
+a host and fetch a new one from its issuer. A static secret raises
+`SandboxConflictError`; an issuer or exchange that did not answer raises
+`SandboxUnavailableError`.
+
+Supported service account operations, admin key only:
+
+- `create_service_account`
+- `remove_service_account`
+
+`create_service_account` returns a `ServiceAccount` with the token the
+service hands out once. Store it. `remove_service_account` revokes it on the
+next request.
+
 Supported template operations:
 
 - `create_template`
@@ -153,7 +175,8 @@ proxy at a host's backing VM (the host must be `bootstrapping` or `active`).
 
 `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
+provider, secrets exchange, 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.
 

{drukbox_python_sdk-0.2.0 → drukbox_python_sdk-0.4.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
@@ -60,6 +62,7 @@ Public exports live in `drukbox_sdk`:
 - `SandboxTemplate`
 - `Secret`
 - `Issuer`
+- `ServiceAccount`
 - `DoctorReport` and `DoctorCheck`
 - `HTTPProxy` and `HTTPProxyAttachment`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
@@ -73,6 +76,7 @@ Supported host operations:
 - `list_hosts`
 - `renew_host`
 - `delete_host`
+- `refresh_secret`
 - `doctor`
 - `aclose`
 
@@ -114,6 +118,24 @@ The response carries no secret. A service name Drukbox does not know raises
 `expires_at` to extend by the service's default TTL; renewal never makes a host
 permanent.
 
+`SandboxHost.service_account` names the service account that created or
+claimed the host, `admin` for an admin key, or `None` for an unclaimed warm
+host.
+
+`refresh_secret` makes the service forget the current value of one secret on
+a host and fetch a new one from its issuer. A static secret raises
+`SandboxConflictError`; an issuer or exchange that did not answer raises
+`SandboxUnavailableError`.
+
+Supported service account operations, admin key only:
+
+- `create_service_account`
+- `remove_service_account`
+
+`create_service_account` returns a `ServiceAccount` with the token the
+service hands out once. Store it. `remove_service_account` revokes it on the
+next request.
+
 Supported template operations:
 
 - `create_template`
@@ -140,7 +162,8 @@ proxy at a host's backing VM (the host must be `bootstrapping` or `active`).
 
 `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
+provider, secrets exchange, 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.
 

{drukbox_python_sdk-0.2.0 → drukbox_python_sdk-0.4.0}/pyproject.toml

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

{drukbox_python_sdk-0.2.0 → drukbox_python_sdk-0.4.0}/src/drukbox_sdk/__init__.py

@@ -14,10 +14,12 @@ from .api import (
     SandboxHost,
     SandboxTemplate,
     Secret,
+    ServiceAccount,
 )
 from .exceptions import (
     SandboxAPIError,
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -35,6 +37,7 @@ __all__ = [
     "SandboxAPI",
     "SandboxAPIError",
     "SandboxAuthError",
+    "SandboxCapacityError",
     "SandboxConflictError",
     "SandboxHost",
     "SandboxNotFoundError",
@@ -44,4 +47,5 @@ __all__ = [
     "SandboxUnavailableError",
     "SandboxValidationError",
     "Secret",
+    "ServiceAccount",
 ]

{drukbox_python_sdk-0.2.0 → drukbox_python_sdk-0.4.0}/src/drukbox_sdk/api.py

@@ -47,6 +47,7 @@ import httpx
 
 from .exceptions import (
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -85,10 +86,15 @@ class SandboxHost:
     different SSH auth model (exe.dev's edge proxy, Tailscale ACLs
     via tailscaled-SSH) return None here. A later ``get_host`` call
     always returns None — the key is not persisted server-side.
+
+    ``service_account`` names the service account that created or claimed
+    the host, ``"admin"`` for an admin key, or None for an unclaimed warm
+    host.
     """
 
     id: str
     name: str
+    service_account: str | None
     status: str
     provider: str
     image: str
@@ -196,6 +202,15 @@ class DoctorReport:
     checks: list[DoctorCheck]
 
 
+@dataclass(frozen=True)
+class ServiceAccount:
+    """A name the service knows a caller by, and the token that caller
+    presents. The service returns the token once, at creation."""
+
+    name: str
+    token: str = field(repr=False)
+
+
 @dataclass(frozen=True)
 class HTTPProxy:
     """An account-bound HTTP proxy as returned by the service.
@@ -401,6 +416,18 @@ class SandboxAPI:
     async def delete_host(self, host_id: uuid.UUID | str) -> None:
         await self._request("DELETE", f"/hosts/{host_id}")
 
+    async def refresh_secret(self, host_id: uuid.UUID | str, service: str) -> None:
+        """Make the service forget the current value of ``service`` on the
+        host and fetch a new one from its issuer.
+
+        Raises :class:`SandboxNotFoundError` for an unknown host or secret,
+        :class:`SandboxConflictError` for a secret with a static value, and
+        :class:`SandboxUnavailableError` when the exchange or the issuer did
+        not answer.
+        """
+
+        await self._request("POST", f"/hosts/{host_id}/secrets/{service}/refresh")
+
     async def create_template(
         self,
         *,
@@ -409,14 +436,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}
@@ -466,6 +494,27 @@ class SandboxAPI:
             checks=[DoctorCheck(**check) for check in data["checks"]],
         )
 
+    async def create_service_account(self, name: str) -> ServiceAccount:
+        """Create a service account and return its token.
+
+        Only an admin key from the service's ``SERVICE_TOKENS`` may call
+        this. A name that already exists raises
+        :class:`SandboxConflictError`; an invalid name raises
+        :class:`SandboxValidationError`.
+        """
+
+        data = await self._request("POST", "/service-accounts", json={"name": name})
+        return ServiceAccount(**data)
+
+    async def remove_service_account(self, name: str) -> None:
+        """Revoke a service account's token and remove the account.
+
+        An unknown name raises :class:`SandboxNotFoundError`; the ``admin``
+        account raises :class:`SandboxConflictError`.
+        """
+
+        await self._request("DELETE", f"/service-accounts/{name}")
+
     async def create_http_proxy(
         self,
         *,
@@ -567,6 +616,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.2.0 → drukbox_python_sdk-0.4.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.2.0 → drukbox_python_sdk-0.4.0}/tests/test_api.py

@@ -28,6 +28,7 @@ from drukbox_sdk import (
     Issuer,
     SandboxAPI,
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -35,6 +36,7 @@ from drukbox_sdk import (
     SandboxUnavailableError,
     SandboxValidationError,
     Secret,
+    ServiceAccount,
 )
 
 BASE_URL = "https://sandbox.test"
@@ -81,6 +83,7 @@ def _host_payload(**overrides: Any) -> dict[str, Any]:
     payload: dict[str, Any] = {
         "id": str(uuid4()),
         "name": "host-abc",
+        "service_account": "admin",
         "status": "provisioning",
         "provider": "exe",
         "image": "ghcr.io/drukbox/sandbox:test",
@@ -421,6 +424,83 @@ async def test_list_hosts_parses_each_record(api: SandboxAPI):
     assert {h.id for h in hosts} == {p["id"] for p in payloads}
 
 
+@respx.mock
+async def test_host_carries_its_service_account(api: SandboxAPI):
+    respx.get(f"{BASE_URL}/hosts/h1").mock(
+        return_value=httpx.Response(200, json=_host_payload(service_account="druks-eu"))
+    )
+
+    host = await api.get_host("h1")
+
+    assert host.service_account == "druks-eu"
+
+
+@respx.mock
+async def test_refresh_secret_posts_and_accepts_204(api: SandboxAPI):
+    route = respx.post(f"{BASE_URL}/hosts/h1/secrets/github/refresh").mock(
+        return_value=httpx.Response(204)
+    )
+
+    await api.refresh_secret("h1", "github")
+
+    assert route.called
+    assert not route.calls.last.request.content
+
+
+@respx.mock
+@pytest.mark.parametrize(
+    "status, error",
+    [
+        (404, SandboxNotFoundError),
+        (409, SandboxConflictError),
+        (503, SandboxUnavailableError),
+    ],
+)
+async def test_refresh_secret_raises_the_typed_error(
+    api: SandboxAPI, status: int, error: type[Exception]
+):
+    respx.post(f"{BASE_URL}/hosts/h1/secrets/github/refresh").mock(
+        return_value=httpx.Response(status, json={"detail": "no"})
+    )
+
+    with pytest.raises(error):
+        await api.refresh_secret("h1", "github")
+
+
+@respx.mock
+async def test_create_service_account_returns_the_token_once(api: SandboxAPI):
+    route = respx.post(f"{BASE_URL}/service-accounts").mock(
+        return_value=httpx.Response(201, json={"name": "druks-eu", "token": "drkb_secret"})
+    )
+
+    account = await api.create_service_account("druks-eu")
+
+    assert json.loads(route.calls.last.request.content) == {"name": "druks-eu"}
+    assert account == ServiceAccount(name="druks-eu", token="drkb_secret")
+    assert "drkb_secret" not in repr(account)
+
+
+@respx.mock
+async def test_create_service_account_409_raises_conflict(api: SandboxAPI):
+    respx.post(f"{BASE_URL}/service-accounts").mock(
+        return_value=httpx.Response(409, json={"detail": "exists"})
+    )
+
+    with pytest.raises(SandboxConflictError):
+        await api.create_service_account("druks-eu")
+
+
+@respx.mock
+async def test_remove_service_account_swallows_204(api: SandboxAPI):
+    route = respx.delete(f"{BASE_URL}/service-accounts/druks-eu").mock(
+        return_value=httpx.Response(204)
+    )
+
+    await api.remove_service_account("druks-eu")
+
+    assert route.called
+
+
 @respx.mock
 async def test_delete_host_swallows_204(api: SandboxAPI):
     host_id = uuid4()
@@ -717,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(