drukbox-python-sdk 0.0.6__tar.gz → 0.1.0__tar.gz

drukbox_python_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Alvarado Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

drukbox_python_sdk-0.0.6/README.md → drukbox_python_sdk-0.1.0/PKG-INFO

@@ -1,11 +1,24 @@
+Metadata-Version: 2.5
+Name: drukbox-python-sdk
+Version: 0.1.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
+Project-URL: Issues, https://github.com/clawhaven/drukbox-python-sdk/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Description-Content-Type: text/markdown
+
 # drukbox-python-sdk
 
 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,7 +70,9 @@ Public exports live in `drukbox_sdk`:
 
 - `SandboxAPI`
 - `SandboxHost`
+- `SandboxTemplate`
 - `DoctorReport` and `DoctorCheck`
+- `HTTPProxy` and `HTTPProxyAttachment`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
   unavailable, and unclassified response errors
 
@@ -67,12 +82,46 @@ Supported host operations:
 - `get_host`
 - `attach`
 - `list_hosts`
+- `renew_host`
 - `delete_host`
 - `doctor`
 - `aclose`
 
 `create_host` supports the service's optional `image`, `env`, `expires_at`,
-`provider`, and `Idempotency-Key` inputs.
+`permanent`, `provider`, `instance_type`, `disk_gb`, `template`, 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.
+
+`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`
+- `delete_http_proxy`
+- `attach_http_proxy`
+- `detach_http_proxy`
+
+HTTP proxies are account-bound exe.dev resources, not host state — deleting a
+host does not remove proxies fronting it. `create_http_proxy` takes an
+origin-only `target` (scheme + host, no path/query/fragment/credentials) and at
+least one `headers` entry; `attach_http_proxy` / `detach_http_proxy` point a
+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
@@ -96,4 +145,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.6/PKG-INFO → drukbox_python_sdk-0.1.0/README.md

@@ -1,19 +1,11 @@
-Metadata-Version: 2.4
-Name: drukbox-python-sdk
-Version: 0.0.6
-Summary: Async Python client for Drukbox.
-Requires-Python: >=3.11
-Requires-Dist: httpx>=0.28
-Description-Content-Type: text/markdown
-
 # drukbox-python-sdk
 
 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
 
@@ -65,7 +57,9 @@ Public exports live in `drukbox_sdk`:
 
 - `SandboxAPI`
 - `SandboxHost`
+- `SandboxTemplate`
 - `DoctorReport` and `DoctorCheck`
+- `HTTPProxy` and `HTTPProxyAttachment`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
   unavailable, and unclassified response errors
 
@@ -75,12 +69,46 @@ Supported host operations:
 - `get_host`
 - `attach`
 - `list_hosts`
+- `renew_host`
 - `delete_host`
 - `doctor`
 - `aclose`
 
 `create_host` supports the service's optional `image`, `env`, `expires_at`,
-`provider`, and `Idempotency-Key` inputs.
+`permanent`, `provider`, `instance_type`, `disk_gb`, `template`, 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.
+
+`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`
+- `delete_http_proxy`
+- `attach_http_proxy`
+- `detach_http_proxy`
+
+HTTP proxies are account-bound exe.dev resources, not host state — deleting a
+host does not remove proxies fronting it. `create_http_proxy` takes an
+origin-only `target` (scheme + host, no path/query/fragment/credentials) and at
+least one `headers` entry; `attach_http_proxy` / `detach_http_proxy` point a
+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
@@ -104,4 +132,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.6 → drukbox_python_sdk-0.1.0}/pyproject.toml

@@ -4,9 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "drukbox-python-sdk"
-version = "0.0.6"
+version = "0.1.0"
 description = "Async Python client for Drukbox."
 readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
 # Tracks the lowest Python any current consumer supports. Bump only
 # when a real consumer needs a 3.12+ feature.
 requires-python = ">=3.11"
@@ -14,6 +16,11 @@ dependencies = [
     "httpx>=0.28",
 ]
 
+[project.urls]
+Homepage = "https://github.com/clawhaven/drukbox-python-sdk"
+Repository = "https://github.com/clawhaven/drukbox-python-sdk"
+Issues = "https://github.com/clawhaven/drukbox-python-sdk/issues"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/drukbox_sdk"]
 

{drukbox_python_sdk-0.0.6 → drukbox_python_sdk-0.1.0}/src/drukbox_sdk/__init__.py

@@ -7,8 +7,11 @@ detail and may change without notice.
 from .api import (
     DoctorCheck,
     DoctorReport,
+    HTTPProxy,
+    HTTPProxyAttachment,
     SandboxAPI,
     SandboxHost,
+    SandboxTemplate,
 )
 from .exceptions import (
     SandboxAPIError,
@@ -24,6 +27,8 @@ from .exceptions import (
 __all__ = [
     "DoctorCheck",
     "DoctorReport",
+    "HTTPProxy",
+    "HTTPProxyAttachment",
     "SandboxAPI",
     "SandboxAPIError",
     "SandboxAuthError",
@@ -32,6 +37,7 @@ __all__ = [
     "SandboxNotFoundError",
     "SandboxProvisioningError",
     "SandboxResponseError",
+    "SandboxTemplate",
     "SandboxUnavailableError",
     "SandboxValidationError",
 ]

{drukbox_python_sdk-0.0.6 → drukbox_python_sdk-0.1.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, fields
+from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, Self
 
@@ -85,6 +92,8 @@ class SandboxHost:
     status: str
     provider: str
     image: str
+    instance_type: str | None
+    disk_gb: int | None
     external_ssh_host: str
     external_ssh_port: int
     ssh_username: str
@@ -99,18 +108,27 @@ class SandboxHost:
     expires_at: str | None
 
 
-_SANDBOX_HOST_FIELDS = {field.name for field in fields(SandboxHost)}
-
-
-def _parse_sandbox_host(data: dict[str, Any]) -> SandboxHost:
-    """Build a :class:`SandboxHost` picking only known fields.
+@dataclass(frozen=True)
+class SandboxTemplate:
+    """Snapshot of a reusable sandbox template as returned by the service.
 
-    Defensive against the service adding new fields — those flow
-    through harmlessly without breaking the SDK on the unsuspecting
-    caller's side.
+    ``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.
     """
 
-    return SandboxHost(**{key: data[key] for key in _SANDBOX_HOST_FIELDS})
+    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)
@@ -134,23 +152,30 @@ class DoctorReport:
     checks: list[DoctorCheck]
 
 
-def _parse_doctor_check(data: dict[str, Any]) -> DoctorCheck:
-    return DoctorCheck(
-        name=data["name"],
-        status=data["status"],
-        detail=data["detail"],
-        latency_ms=data["latency_ms"],
-        hint=data["hint"],
-    )
+@dataclass(frozen=True)
+class HTTPProxy:
+    """An account-bound HTTP proxy as returned by the service.
 
+    ``status`` echoes the lifecycle step the call reached
+    (``"created"``). Proxies are account resources, not host state:
+    deleting a host they front does not remove them.
+    """
+
+    name: str
+    status: str
 
-def _parse_doctor_report(data: dict[str, Any]) -> DoctorReport:
-    return DoctorReport(
-        ok=data["ok"],
-        active_provider=data["active_provider"],
-        tailscale_enabled=data["tailscale_enabled"],
-        checks=[_parse_doctor_check(check) for check in data["checks"]],
-    )
+
+@dataclass(frozen=True)
+class HTTPProxyAttachment:
+    """The result of pointing an HTTP proxy at a host's backing VM.
+
+    ``host_id`` is the string UUID of the attached host; ``status``
+    echoes the step reached (``"attached"``).
+    """
+
+    name: str
+    host_id: str
+    status: str
 
 
 class SandboxAPI:
@@ -204,18 +229,18 @@ 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 = None,
         idempotency_key: str | None = None,
         image: str | None = None,
+        instance_type: str | None = None,
+        permanent: bool = False,
         provider: str | None = None,
+        template: uuid.UUID | str | None = None,
     ) -> SandboxHost:
         """Provision a new host.
 
@@ -234,30 +259,55 @@ class SandboxAPI:
         ``provider`` pins which VM provider serves the request; omit it to
         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: 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.
         """
 
+        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
-        if expires_at is not None:
+        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 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 _parse_sandbox_host(data)
+        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 _parse_sandbox_host(data)
+        return SandboxHost(**data)
 
     async def attach(self, host_id: uuid.UUID | str) -> SandboxHost:
         """Alias for :meth:`get_host` that reads better at call sites
@@ -273,12 +323,84 @@ class SandboxAPI:
 
     async def list_hosts(self) -> list[SandboxHost]:
         data = await self._request("GET", "/hosts")
-        assert isinstance(data, list)
-        return [_parse_sandbox_host(item) for item in data]
+        return [SandboxHost(**item) for item in data]
+
+    async def renew_host(
+        self,
+        host_id: uuid.UUID | str,
+        *,
+        expires_at: datetime | None = None,
+    ) -> SandboxHost:
+        """Extend a host's lease and return the updated record.
+
+        Omit ``expires_at`` to extend by the service's default TTL from
+        now; pass one to set an explicit future expiry. Renewal never
+        makes a host permanent — that is a create-time choice.
+
+        Raises :class:`SandboxNotFoundError` for an unknown host and
+        :class:`SandboxConflictError` when the host is in a non-renewable
+        state (still provisioning, errored, or an unclaimed pool host).
+        """
+
+        payload: dict[str, Any] = {}
+        if expires_at is not None:
+            payload["expires_at"] = expires_at.isoformat()
+        data = await self._request("POST", f"/hosts/{host_id}/renew", json=payload)
+        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.
 
@@ -287,19 +409,65 @@ class SandboxAPI:
         """
 
         data = await self._request("GET", "/doctor")
-        assert isinstance(data, dict)
-        return _parse_doctor_report(data)
+        return DoctorReport(
+            ok=data["ok"],
+            active_provider=data["active_provider"],
+            tailscale_enabled=data["tailscale_enabled"],
+            checks=[DoctorCheck(**check) for check in data["checks"]],
+        )
 
-    async def aclose(self) -> None:
-        if self._client is None:
-            return
-        await self._client.aclose()
-        self._client = None
-        self._client_loop = None
+    async def create_http_proxy(
+        self,
+        *,
+        name: str,
+        target: str,
+        headers: dict[str, str],
+    ) -> HTTPProxy:
+        """Create an account-bound HTTP proxy in front of ``target``.
+
+        ``target`` must be an origin-only URL (scheme + host, no path,
+        query, fragment, or credentials); ``headers`` must carry at least
+        one entry. The service rejects a malformed target or empty headers
+        with :class:`SandboxValidationError`; a name that already exists
+        raises :class:`SandboxConflictError`.
+        """
+
+        payload: dict[str, Any] = {"name": name, "target": target, "headers": headers}
+        data = await self._request("POST", "/http-proxies", json=payload)
+        return HTTPProxy(**data)
 
-    # ------------------------------------------------------------------
-    # Internals
-    # ------------------------------------------------------------------
+    async def delete_http_proxy(self, name: str) -> None:
+        """Delete an HTTP proxy by name. Unknown name raises
+        :class:`SandboxNotFoundError`."""
+
+        await self._request("DELETE", f"/http-proxies/{name}")
+
+    async def attach_http_proxy(
+        self,
+        name: str,
+        host_id: uuid.UUID | str,
+    ) -> HTTPProxyAttachment:
+        """Point proxy ``name`` at ``host_id``'s backing VM.
+
+        The host must have a backing VM (``bootstrapping`` or ``active``);
+        otherwise the service raises :class:`SandboxConflictError`. An
+        unknown host or proxy raises :class:`SandboxNotFoundError`.
+        """
+
+        data = await self._request("POST", f"/http-proxies/{name}/hosts/{host_id}")
+        return HTTPProxyAttachment(**data)
+
+    async def detach_http_proxy(self, name: str, host_id: uuid.UUID | str) -> None:
+        """Detach proxy ``name`` from ``host_id``. Unknown host or proxy
+        raises :class:`SandboxNotFoundError`."""
+
+        await self._request("DELETE", f"/http-proxies/{name}/hosts/{host_id}")
+
+    async def aclose(self) -> None:
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+            self._client_loop = None
 
     async def _request(
         self,
@@ -308,13 +476,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:
@@ -354,9 +522,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:
@@ -365,20 +532,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.6 → drukbox_python_sdk-0.1.0}/tests/test_api.py

@@ -22,11 +22,11 @@ import pytest
 import respx
 
 from drukbox_sdk import (
-    DoctorReport,
+    HTTPProxy,
+    HTTPProxyAttachment,
     SandboxAPI,
     SandboxAuthError,
     SandboxConflictError,
-    SandboxHost,
     SandboxNotFoundError,
     SandboxProvisioningError,
     SandboxResponseError,
@@ -81,6 +81,8 @@ def _host_payload(**overrides: Any) -> dict[str, Any]:
         "status": "provisioning",
         "provider": "exe",
         "image": "ghcr.io/drukbox/sandbox:test",
+        "instance_type": None,
+        "disk_gb": None,
         "external_ssh_host": "203.0.113.42",
         "external_ssh_port": 22,
         "ssh_username": "exedev",
@@ -98,6 +100,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."""
@@ -107,11 +129,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)
@@ -137,7 +154,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"]
@@ -166,9 +182,52 @@ async def test_create_host_omits_image_and_env_when_unset(api: SandboxAPI):
     assert "env" not in body
     assert "expires_at" not in body
     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_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."""
+
+    payload = _host_payload(expires_at=None)
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=payload),
+    )
+
+    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)
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=payload),
+    )
+
+    host = await api.create_host(instance_type="t3.xlarge", disk_gb=100)
+
+    body = route.calls.last.request.content.decode()
+    assert '"instance_type":"t3.xlarge"' in body
+    assert '"disk_gb":100' in body
+    assert host.instance_type == "t3.xlarge"
+    assert host.disk_gb == 100
+
+
 @respx.mock
 async def test_create_host_sends_provider_when_set(api: SandboxAPI):
     payload = _host_payload(provider="hetzner")
@@ -182,6 +241,33 @@ 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_get_host_returns_parsed_host(api: SandboxAPI):
     payload = _host_payload(status="active")
@@ -232,25 +318,55 @@ async def test_delete_host_swallows_204(api: SandboxAPI):
     await api.delete_host(host_id)
 
 
-# ---------------------------------------------------------------------------
-# Forwards compatibility — service adds fields
-# ---------------------------------------------------------------------------
+@respx.mock
+async def test_renew_host_posts_expires_at_and_returns_host(api: SandboxAPI):
+    expires_at = datetime(2026, 7, 1, 12, 0, tzinfo=UTC)
+    payload = _host_payload(status="active", expires_at=expires_at.isoformat())
+    route = respx.post(f"{BASE_URL}/hosts/{payload['id']}/renew").mock(
+        return_value=httpx.Response(200, json=payload),
+    )
+
+    host = await api.renew_host(payload["id"], expires_at=expires_at)
+
+    assert f'"expires_at":"{expires_at.isoformat()}"' in route.calls.last.request.content.decode()
+    assert host.expires_at == payload["expires_at"]
 
 
 @respx.mock
-async def test_unknown_fields_in_host_payload_are_ignored(api: SandboxAPI):
-    """If the service ships a new field tomorrow, today's SDK must not
-    break. The host parser picks known fields only."""
+async def test_renew_host_omits_expires_at_when_unset(api: SandboxAPI):
+    """Omitted expires_at means "extend by the default TTL"; the SDK must
+    send an empty body, not an explicit null."""
 
-    payload = _host_payload(future_field="surprise", another_one=42)
-    respx.get(f"{BASE_URL}/hosts/{payload['id']}").mock(
+    payload = _host_payload(status="active")
+    route = respx.post(f"{BASE_URL}/hosts/{payload['id']}/renew").mock(
         return_value=httpx.Response(200, json=payload),
     )
 
-    host = await api.get_host(payload["id"])
+    await api.renew_host(payload["id"])
+
+    assert "expires_at" not in route.calls.last.request.content.decode()
+
+
+@respx.mock
+async def test_renew_host_404_raises_not_found(api: SandboxAPI):
+    host_id = uuid4()
+    respx.post(f"{BASE_URL}/hosts/{host_id}/renew").mock(
+        return_value=httpx.Response(404, json={"detail": "host not found"}),
+    )
+
+    with pytest.raises(SandboxNotFoundError, match="host not found"):
+        await api.renew_host(host_id)
+
+
+@respx.mock
+async def test_renew_host_409_when_not_renewable(api: SandboxAPI):
+    host_id = uuid4()
+    respx.post(f"{BASE_URL}/hosts/{host_id}/renew").mock(
+        return_value=httpx.Response(409, json={"detail": "cannot renew a host in status error"}),
+    )
 
-    assert host.id == payload["id"]  # Old fields still parsed.
-    assert not hasattr(host, "future_field")  # New field silently dropped.
+    with pytest.raises(SandboxConflictError, match="cannot renew"):
+        await api.renew_host(host_id)
 
 
 @respx.mock
@@ -284,9 +400,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
@@ -433,11 +629,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=[]))
@@ -484,11 +675,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")
@@ -536,7 +722,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
@@ -583,36 +768,116 @@ async def test_doctor_surfaces_failure_with_hint(api: SandboxAPI):
 
 
 @respx.mock
-async def test_doctor_ignores_unknown_check_fields(api: SandboxAPI):
-    """A future service adding a field to a check must not break today's SDK."""
+async def test_doctor_401_raises_sandbox_auth_error(api: SandboxAPI):
+    """Doctor is service-token only; a bad token raises like every other call."""
 
-    payload = _doctor_payload(
-        checks=[
-            {
-                "name": "db",
-                "status": "ok",
-                "detail": "select 1 -> 1",
-                "latency_ms": 2,
-                "hint": None,
-                "future_field": "surprise",
-            },
-        ],
+    respx.get(f"{BASE_URL}/doctor").mock(
+        return_value=httpx.Response(401, json={"detail": "service token required"}),
     )
-    respx.get(f"{BASE_URL}/doctor").mock(return_value=httpx.Response(200, json=payload))
 
-    report = await api.doctor()
+    with pytest.raises(SandboxAuthError, match="service token required"):
+        await api.doctor()
 
-    assert report.checks[0].name == "db"
-    assert not hasattr(report.checks[0], "future_field")
+
+@respx.mock
+async def test_create_http_proxy_posts_payload_and_returns_record(api: SandboxAPI):
+    route = respx.post(f"{BASE_URL}/http-proxies").mock(
+        return_value=httpx.Response(201, json={"name": "gh", "status": "created"}),
+    )
+
+    proxy = await api.create_http_proxy(
+        name="gh",
+        target="https://api.github.com",
+        headers={"Authorization": "Bearer x"},
+    )
+
+    body = route.calls.last.request.content.decode()
+    assert route.calls.last.request.headers["Authorization"] == "Bearer t-test"
+    assert '"name":"gh"' in body
+    assert '"target":"https://api.github.com"' in body
+    assert '"headers":{"Authorization":"Bearer x"}' in body
+    assert proxy == HTTPProxy(name="gh", status="created")
 
 
 @respx.mock
-async def test_doctor_401_raises_sandbox_auth_error(api: SandboxAPI):
-    """Doctor is service-token only; a bad token raises like every other call."""
+async def test_create_http_proxy_409_raises_conflict(api: SandboxAPI):
+    respx.post(f"{BASE_URL}/http-proxies").mock(
+        return_value=httpx.Response(409, json={"detail": "http proxy already exists"}),
+    )
 
-    respx.get(f"{BASE_URL}/doctor").mock(
-        return_value=httpx.Response(401, json={"detail": "service token required"}),
+    with pytest.raises(SandboxConflictError, match="already exists"):
+        await api.create_http_proxy(name="gh", target="https://api.github.com", headers={"X": "y"})
+
+
+@respx.mock
+async def test_create_http_proxy_422_raises_validation(api: SandboxAPI):
+    """A target carrying a path is rejected server-side; the SDK surfaces
+    it as the don't-retry validation error."""
+
+    respx.post(f"{BASE_URL}/http-proxies").mock(
+        return_value=httpx.Response(
+            422,
+            json={"detail": [{"msg": "target URL must not contain a path"}]},
+        ),
     )
 
-    with pytest.raises(SandboxAuthError, match="service token required"):
-        await api.doctor()
+    with pytest.raises(SandboxValidationError, match="must not contain a path"):
+        await api.create_http_proxy(
+            name="gh", target="https://api.github.com/v3", headers={"X": "y"}
+        )
+
+
+@respx.mock
+async def test_delete_http_proxy_swallows_204(api: SandboxAPI):
+    respx.delete(f"{BASE_URL}/http-proxies/gh").mock(return_value=httpx.Response(204))
+
+    await api.delete_http_proxy("gh")
+
+
+@respx.mock
+async def test_delete_http_proxy_404_raises_not_found(api: SandboxAPI):
+    respx.delete(f"{BASE_URL}/http-proxies/gh").mock(
+        return_value=httpx.Response(404, json={"detail": "http proxy not found"}),
+    )
+
+    with pytest.raises(SandboxNotFoundError, match="not found"):
+        await api.delete_http_proxy("gh")
+
+
+@respx.mock
+async def test_attach_http_proxy_returns_attachment(api: SandboxAPI):
+    host_id = uuid4()
+    route = respx.post(f"{BASE_URL}/http-proxies/gh/hosts/{host_id}").mock(
+        return_value=httpx.Response(
+            200, json={"name": "gh", "host_id": str(host_id), "status": "attached"}
+        ),
+    )
+
+    attachment = await api.attach_http_proxy("gh", host_id)
+
+    assert route.called
+    assert attachment == HTTPProxyAttachment(name="gh", host_id=str(host_id), status="attached")
+
+
+@respx.mock
+async def test_attach_http_proxy_409_when_host_has_no_vm(api: SandboxAPI):
+    """Attaching to a host that isn't bootstrapping/active is a state
+    conflict, not a validation error."""
+
+    host_id = uuid4()
+    respx.post(f"{BASE_URL}/http-proxies/gh/hosts/{host_id}").mock(
+        return_value=httpx.Response(409, json={"detail": "host does not have a backing VM"}),
+    )
+
+    with pytest.raises(SandboxConflictError, match="backing VM"):
+        await api.attach_http_proxy("gh", host_id)
+
+
+@respx.mock
+async def test_detach_http_proxy_swallows_204(api: SandboxAPI):
+    host_id = uuid4()
+    respx.delete(f"{BASE_URL}/http-proxies/gh/hosts/{host_id}").mock(
+        return_value=httpx.Response(204),
+    )
+
+    await api.detach_http_proxy("gh", host_id)