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

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

@@ -25,7 +25,7 @@ object is a sandbox host.
 
 ```text
 src/drukbox_sdk/
-  api.py          # SandboxAPI, records, parsers, HTTP request handling
+  api.py          # SandboxAPI, records (SandboxHost, Secret, Issuer, ...), HTTP request handling
   exceptions.py   # SDK exception hierarchy
   __init__.py     # Public exports
 tests/

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

@@ -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.0.7 → drukbox_python_sdk-0.2.0}/README.md

@@ -2,10 +2,10 @@
 
 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
 
@@ -57,6 +57,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,
@@ -74,16 +77,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`
@@ -119,4 +160,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.0.7 → drukbox_python_sdk-0.2.0}/pyproject.toml

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

{drukbox_python_sdk-0.0.7 → drukbox_python_sdk-0.2.0}/src/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_python_sdk-0.0.7 → drukbox_python_sdk-0.2.0}/src/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_python_sdk-0.0.7 → drukbox_python_sdk-0.2.0}/src/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 → drukbox_python_sdk-0.2.0}/tests/test_api.py

@@ -12,6 +12,7 @@ gives us a controllable transport layer so every test stays in-process.
 # pyright: reportPrivateUsage=false
 
 import asyncio
+import json
 from collections.abc import AsyncGenerator
 from datetime import UTC, datetime
 from typing import Any
@@ -22,18 +23,18 @@ import pytest
 import respx
 
 from drukbox_sdk import (
-    DoctorReport,
     HTTPProxy,
     HTTPProxyAttachment,
+    Issuer,
     SandboxAPI,
     SandboxAuthError,
     SandboxConflictError,
-    SandboxHost,
     SandboxNotFoundError,
     SandboxProvisioningError,
     SandboxResponseError,
     SandboxUnavailableError,
     SandboxValidationError,
+    Secret,
 )
 
 BASE_URL = "https://sandbox.test"
@@ -102,6 +103,26 @@ def _host_payload(**overrides: Any) -> dict[str, Any]:
     return payload
 
 
+def _template_payload(**overrides: Any) -> dict[str, Any]:
+    """One canonical template payload used across tests. Each case overrides fields."""
+
+    payload: dict[str, Any] = {
+        "id": str(uuid4()),
+        "provider": "exe",
+        "base_image": "ubuntu-24.04",
+        "setup_script_hash": "ab12" * 16,
+        "label": "Python tools",
+        "image": "",
+        "status": "building",
+        "last_error": "",
+        "created_at": "2026-08-24T12:00:00+00:00",
+        "updated_at": "2026-08-24T12:00:00+00:00",
+        "last_used_at": None,
+    }
+    payload.update(overrides)
+    return payload
+
+
 @pytest.fixture
 async def api() -> AsyncGenerator[SandboxAPI, None]:
     """Fresh SandboxAPI per test. Closed via finalizer."""
@@ -111,11 +132,6 @@ async def api() -> AsyncGenerator[SandboxAPI, None]:
     await client.aclose()
 
 
-# ---------------------------------------------------------------------------
-# Happy paths
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_create_host_posts_payload_and_returns_parsed_host(api: SandboxAPI):
     expires_at = datetime(2026, 6, 1, 12, 0, tzinfo=UTC)
@@ -141,7 +157,6 @@ async def test_create_host_posts_payload_and_returns_parsed_host(api: SandboxAPI
     assert '"env":{"FOO":"bar"}' in body
     assert f'"expires_at":"{expires_at.isoformat()}"' in body
 
-    assert isinstance(host, SandboxHost)
     assert host.id == payload["id"]
     assert host.external_ssh_host == payload["external_ssh_host"]
     assert host.external_ssh_port == payload["external_ssh_port"]
@@ -172,13 +187,13 @@ async def test_create_host_omits_image_and_env_when_unset(api: SandboxAPI):
     assert "provider" not in body
     assert "instance_type" not in body
     assert "disk_gb" not in body
+    assert "template" not in body
     assert "Idempotency-Key" not in route.calls.last.request.headers
 
 
 @respx.mock
-async def test_create_host_none_expires_at_sends_explicit_null(api: SandboxAPI):
-    """Mirroring the wire contract: an explicit ``expires_at=None`` asks for
-    a permanent (never-reaped) host and must serialize as
+async def test_create_host_permanent_sends_explicit_null(api: SandboxAPI):
+    """``permanent=True`` opts out of expiry as the wire's explicit
     ``"expires_at":null`` — distinct from omitting it (default lease),
     covered by test_create_host_omits_image_and_env_when_unset."""
 
@@ -187,11 +202,19 @@ async def test_create_host_none_expires_at_sends_explicit_null(api: SandboxAPI):
         return_value=httpx.Response(201, json=payload),
     )
 
-    await api.create_host(expires_at=None)
+    await api.create_host(permanent=True)
 
     assert '"expires_at":null' in route.calls.last.request.content.decode()
 
 
+async def test_create_host_rejects_permanent_with_expires_at(api: SandboxAPI):
+    with pytest.raises(ValueError, match="permanent"):
+        await api.create_host(
+            permanent=True,
+            expires_at=datetime(2026, 9, 1, tzinfo=UTC),
+        )
+
+
 @respx.mock
 async def test_create_host_sends_sizing_when_set(api: SandboxAPI):
     payload = _host_payload(instance_type="t3.xlarge", disk_gb=100)
@@ -221,6 +244,142 @@ async def test_create_host_sends_provider_when_set(api: SandboxAPI):
     assert host.provider == "hetzner"
 
 
+@respx.mock
+async def test_create_host_sends_template_when_set(api: SandboxAPI):
+    payload = _host_payload()
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=payload),
+    )
+
+    template_id = uuid4()
+    await api.create_host(template=template_id)
+
+    assert f'"template":"{template_id}"' in route.calls.last.request.content.decode()
+
+
+@respx.mock
+async def test_create_host_409_when_template_is_building(api: SandboxAPI):
+    template_id = uuid4()
+    respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(
+            409,
+            json={"detail": f"template {template_id} is building"},
+        ),
+    )
+
+    with pytest.raises(SandboxConflictError, match="is building"):
+        await api.create_host(template=template_id)
+
+
+@respx.mock
+async def test_create_host_sends_secrets_with_only_the_fields_set(api: SandboxAPI):
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=_host_payload()),
+    )
+
+    await api.create_host(
+        secrets={
+            "anthropic": Issuer(
+                "https://mint.test/box-1/anthropic",
+                headers={"Authorization": "Bearer d2d"},
+                refresh="1h",
+            ),
+            "openai": Secret("sk-real"),
+            "acme": Secret("ak_real", host="api.acme.test", auth_variable="ACME_TOKEN"),
+        },
+    )
+
+    body = json.loads(route.calls.last.request.content)
+    assert body["secrets"] == {
+        "anthropic": {
+            "issuer": {
+                "url": "https://mint.test/box-1/anthropic",
+                "headers": {"Authorization": "Bearer d2d"},
+                "refresh": "1h",
+            }
+        },
+        "openai": {"value": "sk-real"},
+        "acme": {"value": "ak_real", "host": "api.acme.test", "auth_variable": "ACME_TOKEN"},
+    }
+
+
+@respx.mock
+async def test_create_host_omits_secrets_when_unset(api: SandboxAPI):
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=_host_payload()),
+    )
+
+    await api.create_host()
+
+    assert "secrets" not in json.loads(route.calls.last.request.content)
+
+
+@respx.mock
+async def test_create_host_keeps_an_empty_auth_prefix(api: SandboxAPI):
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=_host_payload()),
+    )
+    custom = {"host": "api.acme.test", "auth_variable": "ACME_TOKEN", "auth_prefix": ""}
+
+    await api.create_host(
+        secrets={
+            "acme": Secret("ak_real", **custom),
+            "acme-minted": Issuer("https://mint.test/acme", {"X-Key": "k"}, "1h", **custom),
+        },
+    )
+
+    body = json.loads(route.calls.last.request.content)
+    assert body["secrets"]["acme"]["auth_prefix"] == ""
+    assert body["secrets"]["acme-minted"]["auth_prefix"] == ""
+
+
+def test_a_record_never_shows_its_credential():
+    secret = Secret("VALUE_MARKER", host="api.acme.test", auth_variable="ACME_TOKEN")
+    issuer = Issuer("https://mint.test/acme", {"Authorization": "ISSUER_MARKER"}, "1h")
+
+    shown = repr({"acme": secret, "minted": issuer})
+
+    assert "VALUE_MARKER" not in shown
+    assert "ISSUER_MARKER" not in shown
+    assert "api.acme.test" in shown and "https://mint.test/acme" in shown
+
+
+def test_the_custom_service_fields_are_keywords():
+    with pytest.raises(TypeError):
+        Secret("ak_real", "api.acme.test")  # type: ignore[misc]
+    with pytest.raises(TypeError):
+        Issuer("https://mint.test", {"X-Key": "k"}, "1h", "api.acme.test")  # type: ignore[misc]
+
+
+@respx.mock
+async def test_create_host_409_without_the_secrets_proxy_raises_conflict(api: SandboxAPI):
+    respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(
+            409,
+            json={
+                "detail": "secrets need the secrets proxy, which this deployment lacks",
+                "error_code": "SECRETS_PROXY_NOT_CONFIGURED",
+            },
+        ),
+    )
+
+    with pytest.raises(SandboxConflictError, match="secrets proxy"):
+        await api.create_host(secrets={"openai": Secret("sk-real")})
+
+
+@respx.mock
+async def test_create_host_422_for_an_unknown_secret_service_raises_validation(api: SandboxAPI):
+    respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(
+            422,
+            json={"detail": [{"loc": ["body", "secrets"], "msg": "unknown secret service 'acme'"}]},
+        ),
+    )
+
+    with pytest.raises(SandboxValidationError, match="unknown secret service"):
+        await api.create_host(secrets={"acme": Secret("ak_real")})
+
+
 @respx.mock
 async def test_get_host_returns_parsed_host(api: SandboxAPI):
     payload = _host_payload(status="active")
@@ -353,9 +512,89 @@ async def test_get_host_returns_none_private_key_after_create(api: SandboxAPI):
     assert host.private_key is None
 
 
-# ---------------------------------------------------------------------------
-# Error classification
-# ---------------------------------------------------------------------------
+@respx.mock
+async def test_create_template_posts_required_payload_and_returns_building_record(
+    api: SandboxAPI,
+):
+    payload = _template_payload()
+    route = respx.post(f"{BASE_URL}/templates").mock(
+        return_value=httpx.Response(202, json=payload),
+    )
+
+    template = await api.create_template(setup_script="apt-get install -y ripgrep")
+
+    sent = route.calls.last.request
+    assert sent.headers["Authorization"] == "Bearer t-test"
+    assert sent.headers["Accept"] == "application/json"
+    body = sent.content.decode()
+    assert '"setup_script":"apt-get install -y ripgrep"' in body
+    assert "provider" not in body
+    assert "base_image" not in body
+    assert "label" not in body
+    assert template.id == payload["id"]
+    assert template.status == "building"
+    assert template.image == ""
+    assert template.last_used_at is None
+
+
+@respx.mock
+async def test_get_template_returns_parsed_template(api: SandboxAPI):
+    payload = _template_payload(
+        status="available",
+        image="derived:image",
+        last_used_at="2026-08-24T12:30:00+00:00",
+    )
+    respx.get(f"{BASE_URL}/templates/{payload['id']}").mock(
+        return_value=httpx.Response(200, json=payload),
+    )
+
+    template = await api.get_template(payload["id"])
+
+    assert template.status == "available"
+    assert template.image == "derived:image"
+    assert template.last_used_at == payload["last_used_at"]
+
+
+@respx.mock
+async def test_list_templates_parses_records_in_service_order(api: SandboxAPI):
+    payloads = [
+        _template_payload(label="newest"),
+        _template_payload(label="older"),
+    ]
+    respx.get(f"{BASE_URL}/templates").mock(
+        return_value=httpx.Response(200, json=payloads),
+    )
+
+    templates = await api.list_templates()
+
+    assert [template.id for template in templates] == [payload["id"] for payload in payloads]
+    assert [template.label for template in templates] == ["newest", "older"]
+
+
+@respx.mock
+async def test_delete_template_swallows_204(api: SandboxAPI):
+    template_id = uuid4()
+    route = respx.delete(f"{BASE_URL}/templates/{template_id}").mock(
+        return_value=httpx.Response(204),
+    )
+
+    await api.delete_template(template_id)
+
+    assert route.called
+
+
+@respx.mock
+async def test_delete_template_409_while_building(api: SandboxAPI):
+    template_id = uuid4()
+    respx.delete(f"{BASE_URL}/templates/{template_id}").mock(
+        return_value=httpx.Response(
+            409,
+            json={"detail": "TEMPLATE_STATE: template is still building"},
+        ),
+    )
+
+    with pytest.raises(SandboxConflictError, match="TEMPLATE_STATE"):
+        await api.delete_template(template_id)
 
 
 @respx.mock
@@ -502,11 +741,6 @@ async def test_error_detail_absent_uses_fallback_message(api: SandboxAPI):
         await api.list_hosts()
 
 
-# ---------------------------------------------------------------------------
-# Lifecycle + loop affinity
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_aclose_drops_client_and_is_idempotent(api: SandboxAPI):
     respx.get(f"{BASE_URL}/hosts").mock(return_value=httpx.Response(200, json=[]))
@@ -553,11 +787,6 @@ def test_cross_loop_reuse_rebinds_client_without_crashing():
     assert bound_loops[0] is not bound_loops[1]
 
 
-# ---------------------------------------------------------------------------
-# from_env
-# ---------------------------------------------------------------------------
-
-
 def test_from_env_reads_prefixed_vars(monkeypatch: pytest.MonkeyPatch):
     monkeypatch.setenv("SANDBOX_SERVICE_URL", "https://from-env.test")
     monkeypatch.setenv("SANDBOX_SERVICE_TOKEN", "env-token")
@@ -605,7 +834,6 @@ async def test_doctor_parses_report_and_checks(api: SandboxAPI):
 
     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
@@ -663,11 +891,6 @@ async def test_doctor_401_raises_sandbox_auth_error(api: SandboxAPI):
         await api.doctor()
 
 
-# ---------------------------------------------------------------------------
-# HTTP proxies
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_create_http_proxy_posts_payload_and_returns_record(api: SandboxAPI):
     route = respx.post(f"{BASE_URL}/http-proxies").mock(