boxd 0.2.8.dev448__tar.gz → 0.2.9__tar.gz

{boxd-0.2.8.dev448/src/boxd.egg-info → boxd-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.8.dev448
+Version: 0.2.9
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT
@@ -112,6 +112,12 @@ The first of these that is present wins:
 If your key is revoked mid-session, the SDK fails fast with
 `AuthenticationError` rather than retrying.
 
+The exchange endpoint is **rate-limited per source IP** (30 requests / 60s). A
+session token is valid for one hour, so a fleet of workers behind one NAT
+should **mint one token and share it** (`Boxd(token=...)`) rather than each
+process exchanging its own key. On a 429 the SDK waits out one `Retry-After`
+before raising `RateLimitError`.
+
 ### Inside a machine
 
 Inside a boxd machine, `Boxd()` authenticates automatically — no API key
@@ -237,6 +243,24 @@ private to you unless you pass `shared=True`.
 usable. Call `wait_until_ready` before doing anything that depends on it
 running — especially before forking it again.
 
+### Egress allowlist
+
+A machine can be limited to what it may reach on the internet:
+
+```python
+boxd.machines.set_egress_allow("alpha", ["api.stripe.com", "*.github.com", "203.0.113.0/24"])
+boxd.machines.get("alpha").egress_allow
+boxd.machines.set_egress_allow("alpha", [])   # clear: unrestricted again
+```
+
+Entries are hostnames or wildcards, or public IPv4 addresses and CIDRs. Web
+requests are admitted by hostname, everything else by address, with the
+addresses of allowlisted names learned as the machine resolves them. Nothing
+that is not named is reachable. The hosts of any bound secret the machine
+holds are always admitted. Takes effect within a second and is not visible or
+changeable from inside the machine. A fork inherits its source's allowlist; a
+machine restored from a snapshot starts unrestricted.
+
 ### Sizing
 
 There are three sizes: 1 vCPU/4G, 2/8G, 4/16G. Name either dimension and the
@@ -400,7 +424,9 @@ data = boxd.machines.files.download(id, "/app/output.json")   # bytes
 ```
 
 `upload` takes `str` or `bytes`, streams it in chunks so large files are fine,
-and returns the number of bytes the machine confirmed it wrote.
+and returns the number of bytes the machine confirmed it wrote. `download`
+streams too and returns the whole file as `bytes` — there is no size cap, but
+it is all held in memory.
 
 ### Ports and proxies
 
@@ -475,13 +501,32 @@ boxd.env.list(org="acme")
 boxd.env.delete("MODE", scope="all")
 
 boxd.secrets.set("API_TOKEN", "s3cr3t", scope="shared")
-boxd.secrets.list()                # Secret(name, scope) — no value
+boxd.secrets.list()                # Secret(name, scope, domains) — no value
 boxd.secrets.delete("API_TOKEN", scope="shared")
 ```
 
+A secret can be bound to the hosts it may be sent to. The machine then only
+ever holds a placeholder, and the real value is substituted into requests to
+those hosts on the way out:
+
+```python
+boxd.secrets.set("STRIPE_KEY", "sk_live_...", scope="all", domains=["api.stripe.com"])
+```
+
+Inside the machine, `STRIPE_KEY` is an opaque `bxds_…` string. A request to
+`api.stripe.com` carrying it, in a header, the query, the body or Basic auth,
+arrives at Stripe with the real key; a request anywhere else carries the
+useless placeholder. Nothing to configure in the machine, and the placeholder
+does not change when the value is rotated. `domains` is the full desired set:
+setting the secret again without it makes it a plain secret. Wildcards such as
+`*.stripe.com` are accepted; provider-wide ones such as `*.amazonaws.com` are
+refused.
+
 `scope` defaults to `"shared"` on `set` and `delete`; `list` takes `org` only
 and reports every scope. Pass `org="acme"` to any of these to work in an
-organization instead of your personal scope.
+organization instead of your personal scope. With an API key minted in an
+organization your personal scope already lives there, so `org` is only needed
+to reach the organization's `shared`/`all` vars.
 
 `set`, `delete` and `move` each return the server's human-readable
 confirmation of what it did.

{boxd-0.2.8.dev448 → boxd-0.2.9}/README.md

@@ -80,6 +80,12 @@ The first of these that is present wins:
 If your key is revoked mid-session, the SDK fails fast with
 `AuthenticationError` rather than retrying.
 
+The exchange endpoint is **rate-limited per source IP** (30 requests / 60s). A
+session token is valid for one hour, so a fleet of workers behind one NAT
+should **mint one token and share it** (`Boxd(token=...)`) rather than each
+process exchanging its own key. On a 429 the SDK waits out one `Retry-After`
+before raising `RateLimitError`.
+
 ### Inside a machine
 
 Inside a boxd machine, `Boxd()` authenticates automatically — no API key
@@ -205,6 +211,24 @@ private to you unless you pass `shared=True`.
 usable. Call `wait_until_ready` before doing anything that depends on it
 running — especially before forking it again.
 
+### Egress allowlist
+
+A machine can be limited to what it may reach on the internet:
+
+```python
+boxd.machines.set_egress_allow("alpha", ["api.stripe.com", "*.github.com", "203.0.113.0/24"])
+boxd.machines.get("alpha").egress_allow
+boxd.machines.set_egress_allow("alpha", [])   # clear: unrestricted again
+```
+
+Entries are hostnames or wildcards, or public IPv4 addresses and CIDRs. Web
+requests are admitted by hostname, everything else by address, with the
+addresses of allowlisted names learned as the machine resolves them. Nothing
+that is not named is reachable. The hosts of any bound secret the machine
+holds are always admitted. Takes effect within a second and is not visible or
+changeable from inside the machine. A fork inherits its source's allowlist; a
+machine restored from a snapshot starts unrestricted.
+
 ### Sizing
 
 There are three sizes: 1 vCPU/4G, 2/8G, 4/16G. Name either dimension and the
@@ -368,7 +392,9 @@ data = boxd.machines.files.download(id, "/app/output.json")   # bytes
 ```
 
 `upload` takes `str` or `bytes`, streams it in chunks so large files are fine,
-and returns the number of bytes the machine confirmed it wrote.
+and returns the number of bytes the machine confirmed it wrote. `download`
+streams too and returns the whole file as `bytes` — there is no size cap, but
+it is all held in memory.
 
 ### Ports and proxies
 
@@ -443,13 +469,32 @@ boxd.env.list(org="acme")
 boxd.env.delete("MODE", scope="all")
 
 boxd.secrets.set("API_TOKEN", "s3cr3t", scope="shared")
-boxd.secrets.list()                # Secret(name, scope) — no value
+boxd.secrets.list()                # Secret(name, scope, domains) — no value
 boxd.secrets.delete("API_TOKEN", scope="shared")
 ```
 
+A secret can be bound to the hosts it may be sent to. The machine then only
+ever holds a placeholder, and the real value is substituted into requests to
+those hosts on the way out:
+
+```python
+boxd.secrets.set("STRIPE_KEY", "sk_live_...", scope="all", domains=["api.stripe.com"])
+```
+
+Inside the machine, `STRIPE_KEY` is an opaque `bxds_…` string. A request to
+`api.stripe.com` carrying it, in a header, the query, the body or Basic auth,
+arrives at Stripe with the real key; a request anywhere else carries the
+useless placeholder. Nothing to configure in the machine, and the placeholder
+does not change when the value is rotated. `domains` is the full desired set:
+setting the secret again without it makes it a plain secret. Wildcards such as
+`*.stripe.com` are accepted; provider-wide ones such as `*.amazonaws.com` are
+refused.
+
 `scope` defaults to `"shared"` on `set` and `delete`; `list` takes `org` only
 and reports every scope. Pass `org="acme"` to any of these to work in an
-organization instead of your personal scope.
+organization instead of your personal scope. With an API key minted in an
+organization your personal scope already lives there, so `org` is only needed
+to reach the organization's `shared`/`all` vars.
 
 `set`, `delete` and `move` each return the server's human-readable
 confirmation of what it did.

{boxd-0.2.8.dev448 → boxd-0.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boxd"
-version = "0.2.8.dev448"
+version = "0.2.9"
 description = "Python SDK for the boxd cloud VM platform"
 readme = "README.md"
 license = "MIT"

{boxd-0.2.8.dev448 → boxd-0.2.9}/src/boxd/_credentials.py

@@ -26,7 +26,7 @@ from typing import Any
 
 import httpx
 
-from .errors import AuthenticationError
+from .errors import AuthenticationError, RateLimitError
 
 # The in-VM metadata adapter (`crates/boxd-worker/src/metadata.rs`) listens on
 # the VM's default gateway.
@@ -125,7 +125,11 @@ def parse_exchange(status_code: int, body: str, json: Any) -> tuple[str, float]:
     if status_code == 401:
         raise AuthenticationError("invalid or expired API key")
     if status_code == 429:
-        raise AuthenticationError("rate limit exceeded — try again later")
+        raise RateLimitError(
+            "token exchange rate limit exceeded"
+            + (f": {body}" if body else "")
+            + " — a token is valid for 1 hour; reuse one across your workers"
+        )
     if status_code != 200:
         raise AuthenticationError(f"exchange failed: {status_code} {body}")
     try:
@@ -155,6 +159,15 @@ def _expired(expires_at: float, skew: float) -> bool:
     return time.time() > expires_at - skew
 
 
+def _retry_after_secs(resp: httpx.Response) -> float:
+    """Seconds to wait per the ``Retry-After`` header — capped at 60, default 5."""
+    try:
+        secs = float(resp.headers.get("retry-after", ""))
+    except ValueError:
+        return 5.0
+    return min(max(secs, 0.0), 60.0) or 5.0
+
+
 # ── Credential stores ────────────────────────────────────────────────
 
 
@@ -208,14 +221,25 @@ class SyncCredentials(_CredentialsBase):
         return self._cached
 
     def _exchange(self) -> None:
-        try:
-            with httpx.Client(timeout=_HTTP_TIMEOUT_SECS) as client:
-                resp = client.post(self._exchange_url, json={"api_key": self._api_key})
-        except httpx.HTTPError as e:
-            raise AuthenticationError(f"could not reach {self._exchange_url}: {e}") from e
-        self._cached, self._expires_at = parse_exchange(
-            resp.status_code, resp.text, _json_or_none(resp)
-        )
+        for attempt in range(2):
+            try:
+                with httpx.Client(timeout=_HTTP_TIMEOUT_SECS) as client:
+                    resp = client.post(
+                        self._exchange_url, json={"api_key": self._api_key}
+                    )
+            except httpx.HTTPError as e:
+                raise AuthenticationError(
+                    f"could not reach {self._exchange_url}: {e}"
+                ) from e
+            # The exchange endpoint is rate-limited per source IP; a NATed fleet
+            # can trip it legitimately. Wait out one Retry-After before failing.
+            if resp.status_code == 429 and attempt == 0:
+                time.sleep(_retry_after_secs(resp))
+                continue
+            self._cached, self._expires_at = parse_exchange(
+                resp.status_code, resp.text, _json_or_none(resp)
+            )
+            return
 
     def _mint_from_vm(self) -> None:
         base = self._metadata_base()
@@ -260,16 +284,25 @@ class AsyncCredentials(_CredentialsBase):
         return self._cached
 
     async def _exchange(self) -> None:
-        try:
-            async with httpx.AsyncClient(timeout=_HTTP_TIMEOUT_SECS) as client:
-                resp = await client.post(
-                    self._exchange_url, json={"api_key": self._api_key}
-                )
-        except httpx.HTTPError as e:
-            raise AuthenticationError(f"could not reach {self._exchange_url}: {e}") from e
-        self._cached, self._expires_at = parse_exchange(
-            resp.status_code, resp.text, _json_or_none(resp)
-        )
+        for attempt in range(2):
+            try:
+                async with httpx.AsyncClient(timeout=_HTTP_TIMEOUT_SECS) as client:
+                    resp = await client.post(
+                        self._exchange_url, json={"api_key": self._api_key}
+                    )
+            except httpx.HTTPError as e:
+                raise AuthenticationError(
+                    f"could not reach {self._exchange_url}: {e}"
+                ) from e
+            # The exchange endpoint is rate-limited per source IP; a NATed fleet
+            # can trip it legitimately. Wait out one Retry-After before failing.
+            if resp.status_code == 429 and attempt == 0:
+                await asyncio.sleep(_retry_after_secs(resp))
+                continue
+            self._cached, self._expires_at = parse_exchange(
+                resp.status_code, resp.text, _json_or_none(resp)
+            )
+            return
 
     async def _mint_from_vm(self) -> None:
         base = await self._metadata_base()