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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: drukbox-python-sdk
-Version: 0.0.7
+Version: 0.2.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
@@ -15,10 +15,10 @@ Description-Content-Type: text/markdown
 
 Async Python client for the [Drukbox] host API.
 
-The SDK provisions sandbox VMs, reads host state, deletes hosts, and
-returns the SSH connection details a caller needs. It speaks HTTP only:
-SSH sessions, file transfer, command execution, and retry orchestration
-belong in the caller.
+The SDK builds reusable sandbox templates, provisions sandbox VMs, reads host
+state, deletes hosts and templates, and returns the SSH connection details a
+caller needs. It speaks HTTP only: SSH sessions, file transfer, command
+execution, and retry orchestration belong in the caller.
 
 ## Install
 
@@ -70,6 +70,9 @@ Public exports live in `drukbox_sdk`:
 
 - `SandboxAPI`
 - `SandboxHost`
+- `SandboxTemplate`
+- `Secret`
+- `Issuer`
 - `DoctorReport` and `DoctorCheck`
 - `HTTPProxy` and `HTTPProxyAttachment`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
@@ -87,16 +90,54 @@ Supported host operations:
 - `aclose`
 
 `create_host` supports the service's optional `image`, `env`, `expires_at`,
-`provider`, `instance_type`, `disk_gb`, and `Idempotency-Key` inputs.
-`instance_type` (provider-native size, e.g. `t3.xlarge` / `cx33`) and `disk_gb`
-pin the VM shape; omit either for the provider default. `expires_at` mirrors the
-wire contract: omit it for the default lease, pass a datetime for an explicit
-expiry, or pass `None` for a never-reaped (permanent) host.
+`permanent`, `provider`, `instance_type`, `disk_gb`, `template`, `secrets`,
+and `Idempotency-Key` inputs. `instance_type` (provider-native size, e.g.
+`t3.xlarge` / `cx33`) and `disk_gb` pin the VM shape; omit either for the
+provider default. Omit `expires_at` for the default lease, pass a datetime for
+an explicit expiry, or pass `permanent=True` for a never-reaped host.
+`template` accepts a template ID. An explicit `image` wins over it.
+
+`secrets` gives the box credentials it never sees. Each entry is a `Secret`,
+a value the caller holds, or an `Issuer`, a URL Drukbox fetches the value
+from. The box gets a placeholder per entry in the service's variable, and the
+Drukbox swaps it on the way out. A custom service names its `host` and
+`auth_variable`:
+
+```python
+from drukbox_sdk import Issuer, Secret
+
+host = await sandbox.create_host(
+    secrets={
+        "anthropic": Issuer(
+            "https://mint.example/box-1/anthropic",
+            headers={"Authorization": "Bearer ..."},
+            refresh="1h",
+        ),
+        "openai": Secret("sk-..."),
+        "acme": Secret("ak_...", host="api.acme.test", auth_variable="ACME_TOKEN"),
+    },
+)
+```
+
+The response carries no secret. A service name Drukbox does not know raises
+`SandboxValidationError`. A deployment without the secrets proxy raises
+`SandboxConflictError`.
 
 `renew_host` extends a host's lease via `POST /hosts/{id}/renew`. Omit
 `expires_at` to extend by the service's default TTL; renewal never makes a host
 permanent.
 
+Supported template operations:
+
+- `create_template`
+- `get_template`
+- `list_templates`
+- `delete_template`
+
+`create_template` returns immediately with a `building` record. Poll
+`get_template` until the status is `available` or `failed`. A failed record
+carries the reason in `last_error`.
+
 Supported HTTP-proxy operations:
 
 - `create_http_proxy`
@@ -132,4 +173,4 @@ uv run pytest
 Tests use `respx` to fake the Drukbox HTTP API. They do not need a
 real network, VM provider, or Drukbox service.
 
-[Drukbox]: https://github.com/clawhaven/drukbox
+[Drukbox]: https://github.com/czpython/drukbox

drukbox_python_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+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,,

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

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

drukbox_sdk/__init__.py

@@ -9,8 +9,11 @@ from .api import (
     DoctorReport,
     HTTPProxy,
     HTTPProxyAttachment,
+    Issuer,
     SandboxAPI,
     SandboxHost,
+    SandboxTemplate,
+    Secret,
 )
 from .exceptions import (
     SandboxAPIError,
@@ -28,6 +31,7 @@ __all__ = [
     "DoctorReport",
     "HTTPProxy",
     "HTTPProxyAttachment",
+    "Issuer",
     "SandboxAPI",
     "SandboxAPIError",
     "SandboxAuthError",
@@ -36,6 +40,8 @@ __all__ = [
     "SandboxNotFoundError",
     "SandboxProvisioningError",
     "SandboxResponseError",
+    "SandboxTemplate",
     "SandboxUnavailableError",
     "SandboxValidationError",
+    "Secret",
 ]

drukbox_sdk/api.py

@@ -26,13 +26,20 @@ Usage::
         await sandbox.delete_host(host.id)
         await sandbox.aclose()
 
+Templates bake a setup script into a reusable image; hosts fork from it::
+
+    template = await sandbox.create_template(setup_script=script)
+    while template.status == "building":
+        template = await sandbox.get_template(template.id)
+    host = await sandbox.create_host(template=template.id)
+
 For env-backed config use :meth:`SandboxAPI.from_env`.
 """
 
 import asyncio
 import os
 import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Self
 
@@ -58,22 +65,6 @@ _SANDBOX_HTTP_LIMITS = httpx.Limits(
 )
 
 
-class _Unset:
-    """Sentinel distinguishing an omitted argument from an explicit ``None``.
-
-    ``create_host`` mirrors the service's tri-state ``expires_at``: an
-    omitted field means "default lease", an explicit ``null`` means
-    "permanent". A plain ``datetime | None`` default can't tell those two
-    apart, so the omitted case uses this sentinel.
-    """
-
-    def __repr__(self) -> str:
-        return "UNSET"
-
-
-_UNSET = _Unset()
-
-
 @dataclass(frozen=True)
 class SandboxHost:
     """Snapshot of a provisioned host as returned by the service.
@@ -117,6 +108,73 @@ class SandboxHost:
     expires_at: str | None
 
 
+@dataclass(frozen=True, kw_only=True)
+class _Service:
+    """The custom service fields of a secret. None is unset. An empty
+    ``auth_prefix`` is set, and Drukbox reads it as no prefix."""
+
+    host: str | None = None
+    auth_variable: str | None = None
+    auth_header: str | None = None
+    auth_prefix: str | None = None
+
+    def get_service(self) -> dict[str, Any]:
+        fields = {
+            "host": self.host,
+            "auth_variable": self.auth_variable,
+            "auth_header": self.auth_header,
+            "auth_prefix": self.auth_prefix,
+        }
+        return {name: value for name, value in fields.items() if value is not None}
+
+
+@dataclass(frozen=True)
+class Secret(_Service):
+    """A credential the caller holds."""
+
+    value: str = field(repr=False)
+
+    def entry(self) -> dict[str, Any]:
+        return {**self.get_service(), "value": self.value}
+
+
+@dataclass(frozen=True)
+class Issuer(_Service):
+    """A credential Drukbox fetches from ``url`` with ``headers``, and again
+    every ``refresh`` when the answer carries no ``expires_at``."""
+
+    url: str
+    headers: dict[str, str] = field(repr=False)
+    refresh: str
+
+    def entry(self) -> dict[str, Any]:
+        issuer = {"url": self.url, "headers": dict(self.headers), "refresh": self.refresh}
+        return {**self.get_service(), "issuer": issuer}
+
+
+@dataclass(frozen=True)
+class SandboxTemplate:
+    """Snapshot of a reusable sandbox template as returned by the service.
+
+    ``status`` moves from ``"building"`` to ``"available"`` or
+    ``"failed"``. While the build runs, ``image`` is empty. A failed
+    build carries its reason in ``last_error``. The record has no
+    ``setup_script`` because the service never echoes it back.
+    """
+
+    id: str
+    provider: str
+    base_image: str
+    setup_script_hash: str
+    label: str
+    image: str
+    status: str
+    last_error: str
+    created_at: str
+    updated_at: str
+    last_used_at: str | None
+
+
 @dataclass(frozen=True)
 class DoctorCheck:
     """One dependency probe. ``hint`` is a remediation slug, set only on failures."""
@@ -215,20 +273,19 @@ class SandboxAPI:
         timeout = float(os.environ.get(f"{prefix}SERVICE_TIMEOUT", "300"))
         return cls(base_url=url, token=token, timeout=timeout)
 
-    # ------------------------------------------------------------------
-    # Host lifecycle
-    # ------------------------------------------------------------------
-
     async def create_host(
         self,
         *,
         disk_gb: int | None = None,
         env: dict[str, str] | None = None,
-        expires_at: datetime | None | _Unset = _UNSET,
+        expires_at: datetime | None = None,
         idempotency_key: str | None = None,
         image: str | None = None,
         instance_type: str | None = None,
+        permanent: bool = False,
         provider: str | None = None,
+        secrets: dict[str, Secret | Issuer] | None = None,
+        template: uuid.UUID | str | None = None,
     ) -> SandboxHost:
         """Provision a new host.
 
@@ -248,45 +305,58 @@ class SandboxAPI:
         use the service default. An unknown provider raises
         :class:`SandboxResponseError` (the service rejects it with 400).
 
+        ``template`` names a template by its ID, from
+        :meth:`create_template` or :meth:`get_template`. An explicit
+        ``image`` wins when you pass both. A template that is not
+        ``available`` raises :class:`SandboxConflictError`. An unknown
+        ID raises :class:`SandboxResponseError`.
+
         ``instance_type`` (provider-native size, e.g. ``t3.xlarge`` /
         ``cx33``) and ``disk_gb`` (root disk size) pin the VM shape; omit
         either to use the provider's configured default. A size the active
         provider can't serve raises :class:`SandboxResponseError` (400).
 
-        Lease (mirrors the wire contract's tri-state ``expires_at``): omit
-        it for the service's default lease, pass a ``datetime`` for an
-        explicit expiry, or pass ``None`` for a never-reaped (permanent)
-        host — exactly as an omitted field vs. an explicit ``null`` behave
-        on the API.
+        Lease: omit ``expires_at`` for the service's default lease, pass a
+        ``datetime`` for an explicit expiry, or pass ``permanent=True`` for
+        a host the janitor never reaps.
+
+        ``secrets`` maps a service name to a :class:`Secret` or an
+        :class:`Issuer`. The response carries no secret.
         """
 
+        if expires_at and permanent:
+            raise ValueError("a permanent host cannot carry an expires_at")
+
         payload: dict[str, Any] = {}
         if disk_gb is not None:
             payload["disk_gb"] = disk_gb
         if env is not None:
             payload["env"] = env
-        # Sentinel default lets us tell "caller omitted expires_at" (default
-        # lease) from "caller passed None" (explicit null → permanent host).
-        if not isinstance(expires_at, _Unset):
-            payload["expires_at"] = None if expires_at is None else expires_at.isoformat()
+        if expires_at:
+            payload["expires_at"] = expires_at.isoformat()
+        if permanent:
+            # An explicit null on the wire is the opt-out from expiry.
+            payload["expires_at"] = None
         if image is not None:
             payload["image"] = image
         if instance_type is not None:
             payload["instance_type"] = instance_type
         if provider is not None:
             payload["provider"] = provider
+        if secrets:
+            payload["secrets"] = {name: entry.entry() for name, entry in secrets.items()}
+        if template is not None:
+            payload["template"] = str(template)
 
         headers: dict[str, str] = {}
         if idempotency_key is not None:
             headers["Idempotency-Key"] = idempotency_key
 
         data = await self._request("POST", "/hosts", json=payload, headers=headers)
-        assert isinstance(data, dict)
         return SandboxHost(**data)
 
     async def get_host(self, host_id: uuid.UUID | str) -> SandboxHost:
         data = await self._request("GET", f"/hosts/{host_id}")
-        assert isinstance(data, dict)
         return SandboxHost(**data)
 
     async def attach(self, host_id: uuid.UUID | str) -> SandboxHost:
@@ -303,7 +373,6 @@ class SandboxAPI:
 
     async def list_hosts(self) -> list[SandboxHost]:
         data = await self._request("GET", "/hosts")
-        assert isinstance(data, list)
         return [SandboxHost(**item) for item in data]
 
     async def renew_host(
@@ -327,12 +396,61 @@ class SandboxAPI:
         if expires_at is not None:
             payload["expires_at"] = expires_at.isoformat()
         data = await self._request("POST", f"/hosts/{host_id}/renew", json=payload)
-        assert isinstance(data, dict)
         return SandboxHost(**data)
 
     async def delete_host(self, host_id: uuid.UUID | str) -> None:
         await self._request("DELETE", f"/hosts/{host_id}")
 
+    async def create_template(
+        self,
+        *,
+        setup_script: str,
+        provider: str | None = None,
+        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.
+        """
+
+        payload: dict[str, Any] = {"setup_script": setup_script}
+        if provider is not None:
+            payload["provider"] = provider
+        if base_image is not None:
+            payload["base_image"] = base_image
+        if label is not None:
+            payload["label"] = label
+
+        data = await self._request("POST", "/templates", json=payload)
+        return SandboxTemplate(**data)
+
+    async def get_template(self, template_id: uuid.UUID | str) -> SandboxTemplate:
+        """Fetch one template. Callers poll this after :meth:`create_template`."""
+
+        data = await self._request("GET", f"/templates/{template_id}")
+        return SandboxTemplate(**data)
+
+    async def list_templates(self) -> list[SandboxTemplate]:
+        """List templates newest first."""
+
+        data = await self._request("GET", "/templates")
+        return [SandboxTemplate(**item) for item in data]
+
+    async def delete_template(self, template_id: uuid.UUID | str) -> None:
+        """Delete a template.
+
+        A template whose status is ``building`` raises
+        :class:`SandboxConflictError`.
+        """
+
+        await self._request("DELETE", f"/templates/{template_id}")
+
     async def doctor(self) -> DoctorReport:
         """Fetch ``GET /doctor`` — read-only dependency health.
 
@@ -341,7 +459,6 @@ class SandboxAPI:
         """
 
         data = await self._request("GET", "/doctor")
-        assert isinstance(data, dict)
         return DoctorReport(
             ok=data["ok"],
             active_provider=data["active_provider"],
@@ -349,10 +466,6 @@ class SandboxAPI:
             checks=[DoctorCheck(**check) for check in data["checks"]],
         )
 
-    # ------------------------------------------------------------------
-    # HTTP proxies
-    # ------------------------------------------------------------------
-
     async def create_http_proxy(
         self,
         *,
@@ -371,7 +484,6 @@ class SandboxAPI:
 
         payload: dict[str, Any] = {"name": name, "target": target, "headers": headers}
         data = await self._request("POST", "/http-proxies", json=payload)
-        assert isinstance(data, dict)
         return HTTPProxy(**data)
 
     async def delete_http_proxy(self, name: str) -> None:
@@ -393,7 +505,6 @@ class SandboxAPI:
         """
 
         data = await self._request("POST", f"/http-proxies/{name}/hosts/{host_id}")
-        assert isinstance(data, dict)
         return HTTPProxyAttachment(**data)
 
     async def detach_http_proxy(self, name: str, host_id: uuid.UUID | str) -> None:
@@ -403,15 +514,10 @@ class SandboxAPI:
         await self._request("DELETE", f"/http-proxies/{name}/hosts/{host_id}")
 
     async def aclose(self) -> None:
-        if self._client is None:
-            return
-        await self._client.aclose()
-        self._client = None
-        self._client_loop = None
-
-    # ------------------------------------------------------------------
-    # Internals
-    # ------------------------------------------------------------------
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+            self._client_loop = None
 
     async def _request(
         self,
@@ -420,13 +526,13 @@ class SandboxAPI:
         *,
         headers: dict[str, str] | None = None,
         json: dict[str, Any] | None = None,
-    ) -> dict[str, Any] | list[Any]:
+    ) -> Any:
         client = await self._get_client()
         request_headers = {
             "Authorization": f"Bearer {self.token}",
             "Accept": "application/json",
         }
-        if headers is not None:
+        if headers:
             request_headers.update(headers)
 
         try:
@@ -466,9 +572,8 @@ class SandboxAPI:
         if response.status_code == 422:
             # FastAPI's 422 detail is a list of error dicts; join the messages
             # so it reads as a line, not a raw list repr.
-            detail = json_response.get("detail", "validation error")
-            if isinstance(detail, list):
-                detail = "; ".join(item.get("msg", "") for item in detail) or "validation error"
+            errors = json_response.get("detail") or []
+            detail = "; ".join(error.get("msg", "") for error in errors) or "validation error"
             raise SandboxValidationError(detail)
 
         if response.status_code >= 400:
@@ -477,20 +582,16 @@ class SandboxAPI:
 
     async def _get_client(self) -> httpx.AsyncClient:
         running_loop = asyncio.get_running_loop()
-        # Fast-path: client exists and is bound to the current loop.
-        if self._client is not None and self._client_loop is running_loop:
+        if self._client and self._client_loop is running_loop:
             return self._client
-        # Slow-path: either no client yet, or the client is bound to a
-        # stale loop (e.g. fixture teardown). Serialize through the
-        # lock.
-        if self._client_lock is None:
+        if not self._client_lock:
             self._client_lock = asyncio.Lock()
         async with self._client_lock:
             # Re-check under the lock; another coroutine may have raced
             # ahead.
-            if self._client is not None and self._client_loop is running_loop:
+            if self._client and self._client_loop is running_loop:
                 return self._client
-            if self._client is not None:
+            if self._client:
                 # Stale-loop client: closing on its own loop is unsafe,
                 # so drop the reference and rely on GC. httpx will emit
                 # an "unclosed client" warning, which is the correct

drukbox_sdk/exceptions.py

@@ -37,8 +37,8 @@ class SandboxNotFoundError(SandboxAPIError):
 class SandboxConflictError(SandboxAPIError):
     """409 — the operation conflicts with the current state.
 
-    e.g. provisioning a Linux user on a host that already has one with
-    the same name.
+    e.g. a template that is still building, or secrets on a deployment
+    without the secrets proxy configured.
     """
 
 
@@ -53,9 +53,10 @@ class SandboxProvisioningError(SandboxAPIError):
 class SandboxValidationError(SandboxAPIError):
     """422 — the service rejected the request payload as invalid.
 
-    e.g. an env key that isn't a valid environment-variable name, or a
-    proxy target URL carrying a path or credentials. The request is
-    malformed, so retrying it unchanged won't help — fix the input.
+    e.g. an env key that isn't a valid environment-variable name, a
+    proxy target URL carrying a path or credentials, or a secret for a
+    service name Drukbox does not know. The request is malformed, so
+    retrying it unchanged won't help — fix the input.
     """
 
 

drukbox_python_sdk-0.0.7.dist-info/RECORD

@@ -1,7 +0,0 @@
-drukbox_sdk/__init__.py,sha256=pMksdq5D6wBPVQH1PEfMQwXxwyRN7F8Py6ShUQst3Sg,874
-drukbox_sdk/api.py,sha256=SZFo2DhDGbbdENBhdS1yNxvA4QkIAySuGfUJkn9as2s,19123
-drukbox_sdk/exceptions.py,sha256=YecxsuwpHhwzgw-_h9KbXf1WqY6R0JIJrwPY3Eg4e6I,2146
-drukbox_python_sdk-0.0.7.dist-info/METADATA,sha256=X8ym547ccA8-8Bw_WuldPHmi2Qrtg8Tk9d1seJCepxg,4523
-drukbox_python_sdk-0.0.7.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-drukbox_python_sdk-0.0.7.dist-info/licenses/LICENSE,sha256=zM66rWL3BWGJBa_mZPnM0WUomSSZ1xtWVtGQovQ71M8,1078
-drukbox_python_sdk-0.0.7.dist-info/RECORD,,