boax-py 0.1.0__tar.gz

boax_py-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+dist/
+build/

boax_py-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: boax-py
+Version: 0.1.0
+Summary: Official Python SDK for Boax, the self-hosted sandbox and microVM platform.
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# boax
+
+Python SDK for Boax, the self-hosted sandbox and microVM
+platform. Python 3.9 or newer, standard library only.
+
+Your code asks for a profile, capabilities and a placement policy. Boax
+picks the pool; the SDK never needs to know which backend runs the sandbox.
+
+## Install
+
+```sh
+pip install boax
+```
+
+Until the package is published, install from a checkout: `pip install ./sdk/python`.
+
+## Quickstart
+
+```python
+from boax import Boax
+
+# Defaults: BOAX_API_KEY and BOAX_URL (or http://localhost:8080).
+client = Boax()
+
+# Waits until the sandbox is running; pass wait=False to return at once.
+sandbox = client.sandboxes.create(
+    profile="small",
+    placement={"strategy": "private-first", "external": "never"},
+)
+
+result = sandbox.exec("uname -sm")  # a string runs via /bin/sh -c
+print(result.exit_code, result.stdout)
+sandbox.exec(["ls", "-la", "/work"], cwd="/work", timeout_seconds=30)  # a list runs directly
+
+sandbox.files.write("/work/a.txt", "hi")
+text = sandbox.files.read_text("/work/a.txt")
+
+sandbox.delete()
+```
+
+A sandbox is also a context manager that deletes itself on exit:
+
+```python
+with client.sandboxes.create(profile="small") as sandbox:
+    print(sandbox.exec("uname -a").stdout)
+```
+
+## Streaming output
+
+```python
+import sys
+
+for ev in sandbox.exec_stream("make test"):
+    if ev.type == "stdout":
+        sys.stdout.write(ev.data)
+    elif ev.type == "stderr":
+        sys.stderr.write(ev.data)
+    elif ev.type == "exit":
+        print("exit code", ev.exit_code)
+    else:
+        print("backend error:", ev.error)
+```
+
+The command starts when `exec_stream` is called. The iterator ends after
+`exit` or `error`. If the connection drops before either arrives, it raises a
+`connection_error`.
+
+## Errors
+
+Every failure is a `BoaxError` with `code`, `status`, `details` and
+`request_id`. Branch on `code`, not on the message.
+
+```python
+from boax import BoaxError
+
+try:
+    client.sandboxes.create(profile="gpu-large")
+except BoaxError as err:
+    if err.code != "quota_exceeded":
+        raise
+    print("over quota on", err.details.get("dimension"), "request", err.request_id)
+```
+
+Server codes include `invalid_request`, `unauthenticated`, `permission_denied`,
+`not_found`, `conflict`, `quota_exceeded`, `no_eligible_pool`,
+`unsupported_capability`, `unsupported_operation`, `provider_unavailable`,
+`invalid_state`, `rate_limited`, `suspended` and `internal`. The SDK adds
+`timeout` and `connection_error` (with `status` 0). Waiting raises
+`invalid_state` if the sandbox fails or terminates first.
+
+**Retries.** GET, PUT and DELETE requests, and sandbox creation, are retried
+up to `max_retries` times (default 3). Retries happen on 503, on 429
+`rate_limited` (never `quota_exceeded`) and on connection errors, with
+exponential backoff that respects `Retry-After`. Each `create` call sends its
+own `Idempotency-Key`, so a retried create never makes a second sandbox. Pass
+`idempotency_key` to keep the key stable across process restarts. Exec
+and other POSTs are never retried.
+
+## What's covered
+
+| Namespace | Methods |
+|---|---|
+| `sandboxes` | `create`, `get`, `list`, `iterate`, `update`, `delete`, `wait` |
+| `Sandbox` handle | `exec`, `exec_stream`, `files.list/read/read_text/write`, `stop`, `start`, `pause`, `resume`, `snapshot`, `fork`, `expose_port`, `explain_placement`, `refresh`, `update`, `wait`, `delete` |
+| `snapshots` | `list`, `get`, `delete` |
+| `projects` | `list`, `create`, `get`, `delete` |
+| `api_keys` | `list`, `create`, `revoke` |
+| `quotas`, `usage` | `get` |
+| `audit_events` | `list`, `iterate` |
+| `policies` | `list`, `put`, `delete` |
+| `capabilities`, `profiles`, `templates`, `classifications` | `list` |
+| `admin` | `organizations.{list,create,get,update,suspend,resume}`, `projects.set_quota`, `pools.{list,get,create,update,drain,undrain,delete}`, `agents.list`, `trust_report`, `verify_audit`, `terminate_sandbox`, `reconcile` |
+| client | `me`, `version` |
+
+Keyword arguments are snake_case. Records come back as plain dicts keyed exactly
+like the API's JSON (camelCase), typed with `TypedDict` in `boax.types`.
+`ExecResult`, `ExecEvent` and `Page` are dataclasses.
+
+`list` returns one `Page` (`items`, `next_cursor`); `iterate` walks every page:
+
+```python
+for sb in client.sandboxes.iterate(status="running", labels={"team": "ml"}):
+    print(sb.id)
+```
+
+## Options
+
+```python
+Boax(
+    api_key="dly_...",       # default: BOAX_API_KEY
+    base_url="https://...",  # default: BOAX_URL, then http://localhost:8080
+    timeout=120.0,           # socket timeout in seconds; waits and streams set their own
+    max_retries=3,
+    headers={},              # extra headers on every request
+)
+```
+
+Plain `exec` uses the client timeout unless you pass `timeout_seconds`. For long
+commands, pass `timeout_seconds` or use `exec_stream`, which has no socket
+timeout.
+
+## Development
+
+```sh
+python3 -m unittest discover -s tests   # runs against an in-process http.server
+```

boax_py-0.1.0/README.md

@@ -0,0 +1,146 @@
+# boax
+
+Python SDK for Boax, the self-hosted sandbox and microVM
+platform. Python 3.9 or newer, standard library only.
+
+Your code asks for a profile, capabilities and a placement policy. Boax
+picks the pool; the SDK never needs to know which backend runs the sandbox.
+
+## Install
+
+```sh
+pip install boax
+```
+
+Until the package is published, install from a checkout: `pip install ./sdk/python`.
+
+## Quickstart
+
+```python
+from boax import Boax
+
+# Defaults: BOAX_API_KEY and BOAX_URL (or http://localhost:8080).
+client = Boax()
+
+# Waits until the sandbox is running; pass wait=False to return at once.
+sandbox = client.sandboxes.create(
+    profile="small",
+    placement={"strategy": "private-first", "external": "never"},
+)
+
+result = sandbox.exec("uname -sm")  # a string runs via /bin/sh -c
+print(result.exit_code, result.stdout)
+sandbox.exec(["ls", "-la", "/work"], cwd="/work", timeout_seconds=30)  # a list runs directly
+
+sandbox.files.write("/work/a.txt", "hi")
+text = sandbox.files.read_text("/work/a.txt")
+
+sandbox.delete()
+```
+
+A sandbox is also a context manager that deletes itself on exit:
+
+```python
+with client.sandboxes.create(profile="small") as sandbox:
+    print(sandbox.exec("uname -a").stdout)
+```
+
+## Streaming output
+
+```python
+import sys
+
+for ev in sandbox.exec_stream("make test"):
+    if ev.type == "stdout":
+        sys.stdout.write(ev.data)
+    elif ev.type == "stderr":
+        sys.stderr.write(ev.data)
+    elif ev.type == "exit":
+        print("exit code", ev.exit_code)
+    else:
+        print("backend error:", ev.error)
+```
+
+The command starts when `exec_stream` is called. The iterator ends after
+`exit` or `error`. If the connection drops before either arrives, it raises a
+`connection_error`.
+
+## Errors
+
+Every failure is a `BoaxError` with `code`, `status`, `details` and
+`request_id`. Branch on `code`, not on the message.
+
+```python
+from boax import BoaxError
+
+try:
+    client.sandboxes.create(profile="gpu-large")
+except BoaxError as err:
+    if err.code != "quota_exceeded":
+        raise
+    print("over quota on", err.details.get("dimension"), "request", err.request_id)
+```
+
+Server codes include `invalid_request`, `unauthenticated`, `permission_denied`,
+`not_found`, `conflict`, `quota_exceeded`, `no_eligible_pool`,
+`unsupported_capability`, `unsupported_operation`, `provider_unavailable`,
+`invalid_state`, `rate_limited`, `suspended` and `internal`. The SDK adds
+`timeout` and `connection_error` (with `status` 0). Waiting raises
+`invalid_state` if the sandbox fails or terminates first.
+
+**Retries.** GET, PUT and DELETE requests, and sandbox creation, are retried
+up to `max_retries` times (default 3). Retries happen on 503, on 429
+`rate_limited` (never `quota_exceeded`) and on connection errors, with
+exponential backoff that respects `Retry-After`. Each `create` call sends its
+own `Idempotency-Key`, so a retried create never makes a second sandbox. Pass
+`idempotency_key` to keep the key stable across process restarts. Exec
+and other POSTs are never retried.
+
+## What's covered
+
+| Namespace | Methods |
+|---|---|
+| `sandboxes` | `create`, `get`, `list`, `iterate`, `update`, `delete`, `wait` |
+| `Sandbox` handle | `exec`, `exec_stream`, `files.list/read/read_text/write`, `stop`, `start`, `pause`, `resume`, `snapshot`, `fork`, `expose_port`, `explain_placement`, `refresh`, `update`, `wait`, `delete` |
+| `snapshots` | `list`, `get`, `delete` |
+| `projects` | `list`, `create`, `get`, `delete` |
+| `api_keys` | `list`, `create`, `revoke` |
+| `quotas`, `usage` | `get` |
+| `audit_events` | `list`, `iterate` |
+| `policies` | `list`, `put`, `delete` |
+| `capabilities`, `profiles`, `templates`, `classifications` | `list` |
+| `admin` | `organizations.{list,create,get,update,suspend,resume}`, `projects.set_quota`, `pools.{list,get,create,update,drain,undrain,delete}`, `agents.list`, `trust_report`, `verify_audit`, `terminate_sandbox`, `reconcile` |
+| client | `me`, `version` |
+
+Keyword arguments are snake_case. Records come back as plain dicts keyed exactly
+like the API's JSON (camelCase), typed with `TypedDict` in `boax.types`.
+`ExecResult`, `ExecEvent` and `Page` are dataclasses.
+
+`list` returns one `Page` (`items`, `next_cursor`); `iterate` walks every page:
+
+```python
+for sb in client.sandboxes.iterate(status="running", labels={"team": "ml"}):
+    print(sb.id)
+```
+
+## Options
+
+```python
+Boax(
+    api_key="dly_...",       # default: BOAX_API_KEY
+    base_url="https://...",  # default: BOAX_URL, then http://localhost:8080
+    timeout=120.0,           # socket timeout in seconds; waits and streams set their own
+    max_retries=3,
+    headers={},              # extra headers on every request
+)
+```
+
+Plain `exec` uses the client timeout unless you pass `timeout_seconds`. For long
+commands, pass `timeout_seconds` or use `exec_stream`, which has no socket
+timeout.
+
+## Development
+
+```sh
+python3 -m unittest discover -s tests   # runs against an in-process http.server
+```

boax_py-0.1.0/boax/__init__.py

@@ -0,0 +1,22 @@
+"""Official Python SDK for Boax, the self-hosted sandbox and microVM platform."""
+
+from ._client import DEFAULT_BASE_URL, Boax
+from ._errors import BoaxError
+from ._http import __version__
+from ._sandbox import Sandbox, Sandboxes, SandboxFiles
+from .openenv import BoaxEnvironment
+from .types import ExecEvent, ExecResult, Page
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Boax",
+    "BoaxError",
+    "BoaxEnvironment",
+    "ExecEvent",
+    "ExecResult",
+    "Page",
+    "Sandbox",
+    "SandboxFiles",
+    "Sandboxes",
+    "__version__",
+]

boax_py-0.1.0/boax/_admin.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from typing import Any, List, Mapping, Optional
+
+from ._http import HttpClient, path_segment
+from ._sandbox import compact
+from .types import (
+    AuditVerifyResult,
+    CostModel,
+    CreateOrganizationResult,
+    CredentialRef,
+    Organization,
+    Pool,
+    Project,
+    Quota,
+    Secret,
+    UsePoolResult,
+    SandboxInfo,
+    SuspendOrganizationResult,
+    TrustReport,
+)
+
+
+class AdminOrganizations:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> List[Organization]:
+        return self._http.json("GET", "/v1/admin/organizations").get("items") or []
+
+    def create(
+        self, name: str, *, quota: Optional[Quota] = None, default_project: Optional[str] = None
+    ) -> CreateOrganizationResult:
+        """Creates an organization, plus a project named ``default_project`` if given."""
+        body = compact(name=name, quota=quota, defaultProject=default_project)
+        return self._http.json("POST", "/v1/admin/organizations", json=body)
+
+    def get(self, org_id: str) -> Organization:
+        return self._http.json("GET", f"/v1/admin/organizations/{path_segment(org_id)}")
+
+    def update(self, org_id: str, *, name: Optional[str] = None, quota: Optional[Quota] = None) -> Organization:
+        body = compact(name=name, quota=quota)
+        return self._http.json("PATCH", f"/v1/admin/organizations/{path_segment(org_id)}", json=body)
+
+    def suspend(
+        self, org_id: str, *, terminate: bool = False, reason: Optional[str] = None
+    ) -> SuspendOrganizationResult:
+        """Blocks new work for the organization; ``terminate=True`` also ends its sandboxes."""
+        body = compact(terminate=terminate or None, reason=reason)
+        return self._http.json("POST", f"/v1/admin/organizations/{path_segment(org_id)}/suspend", json=body)
+
+    def resume(self, org_id: str, *, reason: Optional[str] = None) -> SuspendOrganizationResult:
+        body = compact(reason=reason)
+        return self._http.json("POST", f"/v1/admin/organizations/{path_segment(org_id)}/resume", json=body)
+
+
+class AdminProjects:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def set_quota(self, project_id: str, quota: Quota) -> Project:
+        """Replaces a project's quota."""
+        return self._http.json("PATCH", f"/v1/admin/projects/{path_segment(project_id)}", json={"quota": quota})
+
+
+class AdminPools:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> List[Pool]:
+        return self._http.json("GET", "/v1/admin/pools").get("items") or []
+
+    def get(self, name: str) -> Pool:
+        return self._http.json("GET", f"/v1/admin/pools/{path_segment(name)}")
+
+    def create(
+        self,
+        name: str,
+        adapter: str,
+        *,
+        trust: Optional[str] = None,
+        region: Optional[str] = None,
+        labels: Optional[Mapping[str, str]] = None,
+        enabled: Optional[bool] = None,
+        max_concurrency: Optional[int] = None,
+        cost_model: Optional[CostModel] = None,
+        config: Optional[Mapping[str, str]] = None,
+        credentials: Optional[CredentialRef] = None,
+    ) -> Pool:
+        """Registers a pool at runtime. ``credentials`` names a server env var, file or stored ``secret``, never a value."""
+        body = compact(
+            name=name,
+            adapter=adapter,
+            trust=trust,
+            region=region,
+            labels=dict(labels) if labels is not None else None,
+            enabled=enabled,
+            maxConcurrency=max_concurrency,
+            costModel=cost_model,
+            config=dict(config) if config is not None else None,
+            credentials=credentials,
+        )
+        return self._http.json("POST", "/v1/admin/pools", json=body)
+
+    def update(
+        self,
+        name: str,
+        *,
+        enabled: Optional[bool] = None,
+        max_concurrency: Optional[int] = None,
+        cost_model: Optional[CostModel] = None,
+        region: Optional[str] = None,
+        credential_ref: Optional[str] = None,
+    ) -> Pool:
+        """``credential_ref`` (API-registered pools only) is ``env:NAME``, ``file:/path`` or ``secret:name``."""
+        body = compact(enabled=enabled, maxConcurrency=max_concurrency, costModel=cost_model, region=region, credentialRef=credential_ref)
+        return self._http.json("PATCH", f"/v1/admin/pools/{path_segment(name)}", json=body)
+
+    def drain(self, name: str) -> Pool:
+        """Stops new placements on the pool; running sandboxes continue."""
+        return self._http.json("POST", f"/v1/admin/pools/{path_segment(name)}/drain")
+
+    def undrain(self, name: str) -> Pool:
+        return self._http.json("POST", f"/v1/admin/pools/{path_segment(name)}/undrain")
+
+    def use(self, name: str, *, approve_external: bool = False) -> UsePoolResult:
+        """Sends new sandboxes to this pool and drains every other one; running sandboxes stay.
+        An external pool must be approved by the global policy, or approved here."""
+        return self._http.json("POST", f"/v1/admin/pools/{path_segment(name)}/use", json=compact(approveExternal=approve_external or None))
+
+    def delete(self, name: str) -> None:
+        """Removes an API-registered pool. Pools from the config file cannot be deleted here."""
+        self._http.json("DELETE", f"/v1/admin/pools/{path_segment(name)}")
+
+
+class AdminSecrets:
+    """Provider credentials stored in Boax, sealed with the server's secrets key."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> List[Secret]:
+        return self._http.json("GET", "/v1/admin/secrets").get("items") or []
+
+    def put(self, name: str, value: str) -> Secret:
+        """Stores or replaces a value. Pools using it switch to the new value without a restart."""
+        return self._http.json("PUT", f"/v1/admin/secrets/{path_segment(name)}", json={"value": value})
+
+    def delete(self, name: str) -> None:
+        """Fails while a pool uses the secret."""
+        self._http.json("DELETE", f"/v1/admin/secrets/{path_segment(name)}")
+
+
+class Admin:
+    """Operator-only endpoints. Every call needs a key with the ``admin`` scope."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+        self.organizations = AdminOrganizations(http)
+        self.projects = AdminProjects(http)
+        self.pools = AdminPools(http)
+        self.secrets = AdminSecrets(http)
+
+    def trust_report(self) -> TrustReport:
+        """Where workloads can go, where they went, and what Boax cannot prove."""
+        return self._http.json("GET", "/v1/admin/trust-report")
+
+    def verify_audit(self) -> AuditVerifyResult:
+        """Verifies the hash chain of the whole audit log."""
+        return self._http.json("GET", "/v1/admin/audit/verify")
+
+    def terminate_sandbox(self, sandbox_id: str, *, reason: Optional[str] = None) -> SandboxInfo:
+        """Terminates any tenant's sandbox."""
+        body: Any = compact(reason=reason)
+        return self._http.json("POST", f"/v1/admin/sandboxes/{path_segment(sandbox_id)}/terminate", json=body)
+
+    def reconcile(self) -> None:
+        """Runs one scheduler reconcile pass now."""
+        self._http.json("POST", "/v1/admin/reconcile")

boax_py-0.1.0/boax/_client.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import os
+from typing import Mapping, Optional
+
+from ._admin import Admin
+from ._errors import BoaxError
+from ._http import HttpClient
+from ._resources import ApiKeys, AuditEvents, Listing, Policies, Projects, Quotas, Snapshots, Usage
+from ._sandbox import Sandboxes
+from .types import Classification, PoolCapabilities, Principal, Profile, Template, VersionInfo
+
+DEFAULT_BASE_URL = "http://localhost:8080"
+
+
+class Boax:
+    """Client for the Boax /v1 API.
+
+    ``api_key`` defaults to ``BOAX_API_KEY`` and ``base_url`` to
+    ``BOAX_URL``, then http://localhost:8080. ``timeout`` is the socket
+    timeout in seconds; long polls and streams size their own. Idempotent
+    requests are retried up to ``max_retries`` times on 429 (rate limited),
+    503 and connection errors.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 120.0,
+        max_retries: int = 3,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("BOAX_API_KEY")
+        if not api_key:
+            raise BoaxError("unauthenticated", "missing API key: pass api_key or set BOAX_API_KEY")
+        self._http = HttpClient(
+            api_key=api_key,
+            base_url=base_url or os.environ.get("BOAX_URL") or DEFAULT_BASE_URL,
+            timeout=timeout,
+            max_retries=max_retries,
+            headers=headers or {},
+        )
+        self.base_url = self._http.base_url
+        self.sandboxes = Sandboxes(self._http)
+        self.snapshots = Snapshots(self._http)
+        self.projects = Projects(self._http)
+        self.api_keys = ApiKeys(self._http)
+        self.quotas = Quotas(self._http)
+        self.usage = Usage(self._http)
+        self.audit_events = AuditEvents(self._http)
+        self.policies = Policies(self._http)
+        #: Pools as tenants see them: trust, region, health and supported features.
+        self.capabilities: Listing[PoolCapabilities] = Listing(self._http, "/v1/capabilities")
+        self.profiles: Listing[Profile] = Listing(self._http, "/v1/profiles")
+        self.templates: Listing[Template] = Listing(self._http, "/v1/templates")
+        self.classifications: Listing[Classification] = Listing(self._http, "/v1/classifications")
+        #: Operator-only endpoints.
+        self.admin = Admin(self._http)
+
+    def __repr__(self) -> str:
+        return f"Boax(base_url={self.base_url!r})"
+
+    def me(self) -> Principal:
+        """Describes the calling key: organization, project, scopes and operator status."""
+        return self._http.json("GET", "/v1/me")
+
+    def version(self) -> VersionInfo:
+        """Server version and installation ID."""
+        return self._http.json("GET", "/version")

boax_py-0.1.0/boax/_errors.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+from typing import Dict, Mapping, Optional
+
+_STATUS_CODES = {
+    400: "invalid_request",
+    401: "unauthenticated",
+    403: "permission_denied",
+    404: "not_found",
+    409: "conflict",
+    422: "no_eligible_pool",
+    429: "rate_limited",
+    501: "unsupported_operation",
+    503: "provider_unavailable",
+}
+
+
+class BoaxError(Exception):
+    """Every failure the SDK reports.
+
+    Branch on ``code``, never on the message. Server codes include
+    ``invalid_request``, ``unauthenticated``, ``permission_denied``,
+    ``not_found``, ``conflict``, ``quota_exceeded``, ``no_eligible_pool``,
+    ``unsupported_capability``, ``unsupported_operation``,
+    ``provider_unavailable``, ``invalid_state``, ``rate_limited``,
+    ``suspended`` and ``internal``. The SDK itself raises ``timeout`` and
+    ``connection_error`` with ``status`` 0.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status: int = 0,
+        details: Optional[Mapping[str, str]] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.details: Dict[str, str] = dict(details or {})
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+    def __repr__(self) -> str:
+        return f"BoaxError(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+
+def error_from_response(status: int, body: bytes, header_request_id: Optional[str]) -> BoaxError:
+    """Builds an error from a non-2xx response, tolerating non-JSON bodies from proxies."""
+    err: dict = {}
+    try:
+        envelope = json.loads(body.decode("utf-8"))
+        if isinstance(envelope, dict) and isinstance(envelope.get("error"), dict):
+            err = envelope["error"]
+    except (ValueError, UnicodeDecodeError):
+        pass
+    message = err.get("message")
+    if not isinstance(message, str):
+        text = body.decode("utf-8", "replace")[:200]
+        message = f"HTTP {status}" + (f": {text}" if text else "")
+    details = err.get("details")
+    return BoaxError(
+        err["code"] if isinstance(err.get("code"), str) else _STATUS_CODES.get(status, "internal"),
+        message,
+        status=status,
+        details=details if isinstance(details, dict) else None,
+        request_id=err.get("requestId") or header_request_id,
+    )