boxd 0.2.19.dev910__py3-none-any.whl → 0.2.20.dev929__py3-none-any.whl

boxd/__init__.py

@@ -26,6 +26,13 @@ from .errors import (
     AuthenticationError,
     BoxdError,
     ConflictError,
+    MachineAgentOutdatedError,
+    MachineFileExistsError,
+    MachineFileNotFoundError,
+    MachineFilesystemError,
+    MachineIsADirectoryError,
+    MachineNotADirectoryError,
+    MachinePermissionError,
     NotFoundError,
     PermissionDeniedError,
     RateLimitError,
@@ -51,6 +58,8 @@ from .models import (
     DiskAttachment,
     DiskStatus,
     EnvVar,
+    FsEntry,
+    FsEntryType,
     ExecResult,
     SelfDeleteResult,
     ExposedPort,
@@ -161,6 +170,8 @@ __all__ = [
     "DiskStatus",
     "EnvVar",
     "ExecResult",
+    "FsEntry",
+    "FsEntryType",
     "SelfDeleteResult",
     "ExposedPort",
     "BillingActivityEntry",
@@ -235,6 +246,13 @@ __all__ = [
     "AuthenticationError",
     "BoxdError",
     "ConflictError",
+    "MachineAgentOutdatedError",
+    "MachineFileExistsError",
+    "MachineFileNotFoundError",
+    "MachineFilesystemError",
+    "MachineIsADirectoryError",
+    "MachineNotADirectoryError",
+    "MachinePermissionError",
     "NotFoundError",
     "PermissionDeniedError",
     "RateLimitError",

boxd/_credentials.py

@@ -10,7 +10,7 @@ Resolution order, first match wins:
 2. explicit ``api_key``         — exchanged for a JWT
 3. ``BOXD_TOKEN``, then ``BOXD_API_KEY`` — same handling
 4. in-VM metadata adapter       — no credentials required
-5. otherwise :class:`AuthenticationError`
+5. otherwise :class:`AuthenticationError` (reason ``"missing_credentials"``)
 
 Steps 4 and 5 need I/O, so the decision lands on the first request rather than
 in ``__init__``: constructing a client never blocks on a network probe.
@@ -26,7 +26,13 @@ from typing import Any
 
 import httpx
 
-from .errors import AuthenticationError, RateLimitError
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    PermissionDeniedError,
+    RateLimitError,
+)
 
 # The in-VM metadata adapter listens on the VM's default gateway.
 METADATA_PORT = 9002
@@ -48,6 +54,15 @@ _NO_CREDENTIALS = (
     "no credentials: pass api_key= or token=, set BOXD_API_KEY / BOXD_TOKEN, "
     "or run inside a boxd VM"
 )
+# The environment says "machine" and there is a gateway, but nothing answered
+# on it. An isolated machine looks exactly like this (it keeps the hints but
+# has no metadata adapter), and so does an adapter outage: there is no telling
+# them apart from here, so this stays terminal and says what to do instead.
+_ADAPTER_SILENT = (
+    "no credentials: the machine's metadata adapter at {url} did not answer "
+    "(isolated machines have none); pass api_key= or token=, or set "
+    "BOXD_API_KEY / BOXD_TOKEN"
+)
 
 
 # ── In-VM detection ──────────────────────────────────────────────────
@@ -116,61 +131,123 @@ async def probe_async(host: str, port: int, timeout: float = _PROBE_TIMEOUT_SECS
     return True
 
 
-def metadata_base(not_inside: str = _NO_CREDENTIALS) -> str:
-    """The in-VM metadata adapter's base URL, or ``AuthenticationError(not_inside)``
-    when this code is not running inside a boxd machine. Detection needs BOTH
-    signals, the environment hint and a live probe — neither alone is
-    sufficient."""
+def _missing(message: str) -> AuthenticationError:
+    return AuthenticationError(
+        message, code="unauthenticated", reason="missing_credentials"
+    )
+
+
+def metadata_base(
+    not_inside: str = _NO_CREDENTIALS, silent: str = _ADAPTER_SILENT
+) -> str:
+    """The in-VM metadata adapter's base URL, or ``AuthenticationError``
+    (reason ``"missing_credentials"``) when there is none to use. Detection
+    needs BOTH signals, the environment hint and a live probe — neither alone
+    is sufficient.
+
+    The message is ``not_inside`` when this doesn't look like a machine, and
+    ``silent`` (formatted with ``url``) when it does but the adapter didn't
+    answer. Nothing is cached: the next call probes again."""
     if not looks_like_a_machine():
-        raise AuthenticationError(not_inside)
+        raise _missing(not_inside)
     gateway = detect_gateway()
-    if not gateway or not probe(gateway, METADATA_PORT):
-        raise AuthenticationError(not_inside)
-    return f"http://{gateway}:{METADATA_PORT}"
+    if not gateway:
+        raise _missing(not_inside)
+    base = f"http://{gateway}:{METADATA_PORT}"
+    if not probe(gateway, METADATA_PORT):
+        raise _missing(silent.format(url=base))
+    return base
 
 
-async def metadata_base_async(not_inside: str = _NO_CREDENTIALS) -> str:
+async def metadata_base_async(
+    not_inside: str = _NO_CREDENTIALS, silent: str = _ADAPTER_SILENT
+) -> str:
     """Async twin of :func:`metadata_base`."""
     if not looks_like_a_machine():
-        raise AuthenticationError(not_inside)
+        raise _missing(not_inside)
     gateway = detect_gateway()
-    if not gateway or not await probe_async(gateway, METADATA_PORT):
-        raise AuthenticationError(not_inside)
-    return f"http://{gateway}:{METADATA_PORT}"
+    if not gateway:
+        raise _missing(not_inside)
+    base = f"http://{gateway}:{METADATA_PORT}"
+    if not await probe_async(gateway, METADATA_PORT):
+        raise _missing(silent.format(url=base))
+    return base
 
 
 # ── Response parsing (shared by both clients) ────────────────────────
 
 
 def parse_exchange(status_code: int, body: str, json: Any) -> tuple[str, float]:
-    """Validate an API-key exchange response → ``(token, expires_at)``."""
+    """Validate an API-key exchange response → ``(token, expires_at)``.
+
+    Only a 401 means the key itself was refused. An account that can't use
+    the API is a 403; anything else the exchange answers is its own failure,
+    not the key's.
+    """
     if status_code == 401:
-        raise AuthenticationError("invalid or expired API key")
+        raise AuthenticationError(
+            "invalid or expired API key",
+            code="unauthenticated",
+            reason="invalid_api_key",
+            http_status=status_code,
+        )
     if status_code == 429:
         raise RateLimitError(
             "token exchange rate limit exceeded"
             + (f": {body}" if body else "")
-            + " — a token is valid for 1 hour; reuse one across your workers"
+            + " — a token is valid for 1 hour; reuse one across your workers",
+            code="resource_exhausted",
+            http_status=status_code,
+        )
+    if status_code == 403:
+        raise PermissionDeniedError(
+            f"API key refused: {body}" if body else "API key refused",
+            code="permission_denied",
+            http_status=status_code,
         )
     if status_code != 200:
-        raise AuthenticationError(f"exchange failed: {status_code} {body}")
+        raise APIStatusError(
+            f"exchange failed: {status_code} {body}", http_status=status_code
+        )
     try:
         return str(json["token"]), float(json["expires_at"])
     except (TypeError, KeyError, ValueError) as e:
-        raise AuthenticationError(f"malformed exchange response: {body}") from e
+        raise APIStatusError(
+            f"malformed exchange response: {body}", http_status=status_code
+        ) from e
 
 
 def parse_vm_token(status_code: int, body: str, json: Any) -> tuple[str, float, str | None]:
-    """Validate a metadata-adapter token response → ``(token, expires_at, api_url)``."""
+    """Validate a metadata-adapter token response → ``(token, expires_at, api_url)``.
+
+    The adapter authenticates the machine by where the request comes from, so
+    it has no "wrong credential" answer: a 403 is a refusal (e.g. a disabled
+    account), anything else is the adapter's own failure.
+    """
+    if status_code == 403:
+        raise PermissionDeniedError(
+            f"in-VM token request refused: {body}",
+            code="permission_denied",
+            http_status=status_code,
+        )
+    if status_code == 429:
+        raise RateLimitError(
+            f"in-VM token request rate limited: {body}",
+            code="resource_exhausted",
+            http_status=status_code,
+        )
     if status_code != 200:
-        raise AuthenticationError(
-            f"in-VM token request failed: {status_code} {body}"
+        raise APIStatusError(
+            f"in-VM token request failed: {status_code} {body}",
+            http_status=status_code,
         )
     try:
         token = str(json["token"])
         expires_at = float(json["expires_at"])
     except (TypeError, KeyError, ValueError) as e:
-        raise AuthenticationError(f"malformed in-VM token response: {body}") from e
+        raise APIStatusError(
+            f"malformed in-VM token response: {body}", http_status=status_code
+        ) from e
     # The VM reports its own cluster, which is what lets an unconfigured
     # `Boxd()` work identically on dev, staging, metal and prod.
     api_url = json.get("api_url") or None
@@ -250,7 +327,7 @@ class SyncCredentials(_CredentialsBase):
                         self._exchange_url, json={"api_key": self._api_key}
                     )
             except httpx.HTTPError as e:
-                raise AuthenticationError(
+                raise APIConnectionError(
                     f"could not reach {self._exchange_url}: {e}"
                 ) from e
             # The exchange endpoint is rate-limited per source IP; a NATed fleet
@@ -269,7 +346,9 @@ class SyncCredentials(_CredentialsBase):
             with httpx.Client(timeout=_HTTP_TIMEOUT_SECS) as client:
                 resp = client.get(base + METADATA_TOKEN_PATH)
         except httpx.HTTPError as e:
-            raise AuthenticationError(f"in-VM token request failed: {e}") from e
+            raise APIConnectionError(
+                f"could not reach the in-VM metadata adapter: {e}"
+            ) from e
         token, expires_at, api_url = parse_vm_token(
             resp.status_code, resp.text, _json_or_none(resp)
         )
@@ -307,7 +386,7 @@ class AsyncCredentials(_CredentialsBase):
                         self._exchange_url, json={"api_key": self._api_key}
                     )
             except httpx.HTTPError as e:
-                raise AuthenticationError(
+                raise APIConnectionError(
                     f"could not reach {self._exchange_url}: {e}"
                 ) from e
             # The exchange endpoint is rate-limited per source IP; a NATed fleet
@@ -328,7 +407,9 @@ class AsyncCredentials(_CredentialsBase):
                     base + METADATA_TOKEN_PATH
                 )
         except httpx.HTTPError as e:
-            raise AuthenticationError(f"in-VM token request failed: {e}") from e
+            raise APIConnectionError(
+                f"could not reach the in-VM metadata adapter: {e}"
+            ) from e
         token, expires_at, api_url = parse_vm_token(
             resp.status_code, resp.text, _json_or_none(resp)
         )