drukbox-python-sdk 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

{drukbox_python_sdk-0.2.0.dist-info → drukbox_python_sdk-0.4.0.dist-info}/METADATA

@@ -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.4.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+drukbox_sdk/__init__.py,sha256=OgssAANGnl49_1N_EKMXSDlgWfedO9jUAnLVxgkJY2Q,1066
+drukbox_sdk/api.py,sha256=Xd_UhCYsE_kRojDEBIacHGHrOB2msDHfrE1WfOBbOBc,24501
+drukbox_sdk/exceptions.py,sha256=0CKbb0Ec4RSWPB8t31WJgO1yQQ10BwTPqoqS1_EieB4,2599
+drukbox_python_sdk-0.4.0.dist-info/METADATA,sha256=kFilTF-v_ongltIWRUJrc1TLboG29gWCLCwABTPTmGo,6734
+drukbox_python_sdk-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+drukbox_python_sdk-0.4.0.dist-info/licenses/LICENSE,sha256=zM66rWL3BWGJBa_mZPnM0WUomSSZ1xtWVtGQovQ71M8,1078
+drukbox_python_sdk-0.4.0.dist-info/RECORD,,

{drukbox_python_sdk-0.2.0.dist-info → drukbox_python_sdk-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any

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_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_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.dist-info/RECORD

@@ -1,7 +0,0 @@
-drukbox_sdk/__init__.py,sha256=7LHAef5BXUaEN_pk9pXeowyV8CuQxWnbghANSZZTcPM,970
-drukbox_sdk/api.py,sha256=tcVaHQom-O2Xq8BbThFTjiRt7zHkWw3a6WYwC4rW3c0,22300
-drukbox_sdk/exceptions.py,sha256=Vzs4zVOywWsWfiZm6vgQ65ScI3Nn7zLGVj-8eT1YAR0,2224
-drukbox_python_sdk-0.2.0.dist-info/METADATA,sha256=3XKJgIsi_BHqaCuNhNaOSa6MSje_67u40BlCATpm3s4,5870
-drukbox_python_sdk-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-drukbox_python_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=zM66rWL3BWGJBa_mZPnM0WUomSSZ1xtWVtGQovQ71M8,1078
-drukbox_python_sdk-0.2.0.dist-info/RECORD,,