boxd 0.2.22.dev936__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {boxd-0.2.22.dev936/src/boxd.egg-info → boxd-0.3.0}/PKG-INFO +73 -3
  2. {boxd-0.2.22.dev936 → boxd-0.3.0}/README.md +72 -2
  3. {boxd-0.2.22.dev936 → boxd-0.3.0}/pyproject.toml +1 -1
  4. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/__init__.py +12 -0
  5. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_client.py +52 -12
  6. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_credentials.py +25 -5
  7. boxd-0.3.0/src/boxd/_generated/api_pb2.py +696 -0
  8. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_generated/api_pb2_grpc.py +141 -0
  9. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_mappers.py +40 -3
  10. boxd-0.3.0/src/boxd/_regions.py +839 -0
  11. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_requests.py +25 -2
  12. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_streaming.py +29 -4
  13. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_transport.py +103 -9
  14. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_urls.py +59 -0
  15. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/errors.py +33 -1
  16. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/models.py +95 -3
  17. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/disks.py +64 -17
  18. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/domains.py +22 -10
  19. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/fs.py +112 -29
  20. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/machines.py +684 -232
  21. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/orgs.py +129 -16
  22. boxd-0.3.0/src/boxd/resources/regions.py +37 -0
  23. boxd-0.3.0/src/boxd/resources/snapshots.py +169 -0
  24. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/teams.py +34 -14
  25. {boxd-0.2.22.dev936 → boxd-0.3.0/src/boxd.egg-info}/PKG-INFO +73 -3
  26. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd.egg-info/SOURCES.txt +5 -0
  27. boxd-0.3.0/tests/test_create_in_one_call.py +136 -0
  28. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_namespaces.py +1 -0
  29. boxd-0.3.0/tests/test_raw_key.py +302 -0
  30. boxd-0.3.0/tests/test_regions.py +1141 -0
  31. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_streaming.py +3 -1
  32. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_transport.py +1 -1
  33. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_urls.py +44 -1
  34. boxd-0.2.22.dev936/src/boxd/_generated/api_pb2.py +0 -678
  35. boxd-0.2.22.dev936/src/boxd/resources/snapshots.py +0 -111
  36. {boxd-0.2.22.dev936 → boxd-0.3.0}/LICENSE +0 -0
  37. {boxd-0.2.22.dev936 → boxd-0.3.0}/setup.cfg +0 -0
  38. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_generated/__init__.py +0 -0
  39. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/_version_check.py +0 -0
  40. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/py.typed +0 -0
  41. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/__init__.py +0 -0
  42. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/account.py +0 -0
  43. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/credentials.py +0 -0
  44. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/resources/vars.py +0 -0
  45. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd/spec.py +0 -0
  46. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd.egg-info/dependency_links.txt +0 -0
  47. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd.egg-info/requires.txt +0 -0
  48. {boxd-0.2.22.dev936 → boxd-0.3.0}/src/boxd.egg-info/top_level.txt +0 -0
  49. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_credentials.py +0 -0
  50. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_delete_self.py +0 -0
  51. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_fs.py +0 -0
  52. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_mappers.py +0 -0
  53. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_python_versions.py +0 -0
  54. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_requests.py +0 -0
  55. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_spec.py +0 -0
  56. {boxd-0.2.22.dev936 → boxd-0.3.0}/tests/test_version_check.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: boxd
3
- Version: 0.2.22.dev936
3
+ Version: 0.3.0
4
4
  Summary: Python SDK for the boxd cloud VM platform
5
5
  Author: Azin
6
6
  License-Expression: MIT
@@ -75,6 +75,7 @@ Resources return plain data — a `Machine` has fields, not methods.
75
75
  ```python
76
76
  Boxd() # production
77
77
  Boxd(api_key="bxd_...")
78
+ Boxd(region="nyc") # machines in another region
78
79
  Boxd(base_url="https://boxd.example.com:9443") # any other cluster
79
80
  ```
80
81
 
@@ -85,6 +86,7 @@ Every argument is keyword-only.
85
86
  | `api_key` | `BOXD_API_KEY` | — |
86
87
  | `token` | `BOXD_TOKEN` | — |
87
88
  | `base_url` | `BOXD_BASE_URL` (or the deprecated `BOXD_API_URL`) | `https://boxd.sh:9443` |
89
+ | `region` | `BOXD_REGION` | the region `base_url` serves — see [Regions](#regions) |
88
90
  | `timeout` | — | 60.0 seconds |
89
91
  | `max_retries` | — | 2 |
90
92
 
@@ -181,6 +183,68 @@ an async generator you drive with `async for`.
181
183
  Use `AsyncBoxd` when you already have an event loop (FastAPI, asyncio scripts,
182
184
  anyio). Use `Boxd` everywhere else — scripts, notebooks, Django views.
183
185
 
186
+ ## Regions
187
+
188
+ boxd runs in several regions, each with its own API. A machine, snapshot or
189
+ disk lives in one region. Your account, organizations, API keys, environment
190
+ variables and billing live in your home region and work in every region with
191
+ the same credential.
192
+
193
+ Pick a region for the client, or for one call:
194
+
195
+ ```python
196
+ boxd = Boxd(region="nyc") # or set BOXD_REGION=nyc
197
+ boxd.machines.create("api") # created in nyc
198
+ boxd.machines.get("api") # looked up in nyc
199
+ boxd.machines.get("web", region="fra") # this call only
200
+ boxd.region # "nyc"
201
+ ```
202
+
203
+ With no region, every call goes to `base_url`, as before. Every method on
204
+ machines (and `files`, `fs`, `ports`, `proxies`, `checkpoints`, `backups`),
205
+ snapshots, disks, custom domains and org domains takes `region=`. Account and
206
+ organization calls always go to `base_url`.
207
+
208
+ ```python
209
+ for r in boxd.regions.list():
210
+ r.id, r.name, r.home, r.org_state # "enabled" | "requested" | "available"
211
+
212
+ machines = boxd.machines.list() # the client's region
213
+ machines.elsewhere # [RegionCount(region="fra", count=3)]
214
+ everywhere = boxd.machines.list(region="all")
215
+ [(m.name, m.region) for m in everywhere]
216
+ everywhere.unavailable # regions that could not be reached just now
217
+ ```
218
+
219
+ `snapshots.list()` and `disks.list()` take `region="all"` and carry
220
+ `elsewhere` too. `machine.region`, `snapshot.region` and `disk.region` say
221
+ where each one lives.
222
+
223
+ An organization can use its home region and the regions enabled for it.
224
+ Creating or listing machines or snapshots in any other region raises
225
+ `RegionNotEnabledError`. An org admin can ask for one:
226
+
227
+ ```python
228
+ boxd.orgs.regions("acme") # where the org stands with each region
229
+ boxd.orgs.request_region("nyc", "acme") # "requested", or "enabled" if it has it
230
+ boxd.orgs.set_default_region("nyc", "acme") # recorded for the org; the SDK
231
+ boxd.orgs.get_default_region("acme") # does not route by it
232
+ boxd.orgs.clear_default_region("acme")
233
+ ```
234
+
235
+ When a machine, snapshot or disk is not in the region a call went to, the SDK
236
+ asks where else your organizations have that name, and the `NotFoundError`
237
+ says so:
238
+
239
+ ```python
240
+ try:
241
+ boxd.machines.get("web")
242
+ except NotFoundError as e:
243
+ print(e) # ...; there is a machine "web" in fra: pass region="fra"
244
+ e.elsewhere # [ElsewhereItem(region="fra", name="web", org_id=..., id=...)]
245
+ e.close # names one or two letters off, in other regions
246
+ ```
247
+
184
248
  ## Machines
185
249
 
186
250
  ```python
@@ -646,6 +710,7 @@ machine.source.name # source machine, or snapshot name
646
710
  machine.source.version # int | None — snapshots only; a fork has none
647
711
  machine.source.id # str | None — provenance; may not resolve
648
712
 
713
+ machine.region # str | None — where it lives; None when boxd runs in one region
649
714
  machine.hibernated_at # datetime | None — None = not hibernated
650
715
  machine.last_connected_at # datetime | None — None = never connected
651
716
  machine.boot_time_ms # int | None — last boot; None = never booted
@@ -1021,11 +1086,13 @@ snapshot.memory_bytes
1021
1086
  snapshot.use_count # machines restored from it so far
1022
1087
  snapshot.storage # "local" | "archiving" | "archived" | "unarchiving"
1023
1088
  snapshot.archived # True unless storage is "local": machines can't be created from it
1089
+ snapshot.region # str | None — where it lives
1024
1090
 
1025
1091
  volume = boxd.disks.list()[0]
1026
1092
  volume.id, volume.name, volume.size_bytes
1027
1093
  volume.status # "creating" | "ready" | "destroyed" — attach once "ready"
1028
1094
  volume.created_at # datetime | None
1095
+ volume.region # str | None — where it lives
1029
1096
  volume.attachments # [DiskAttachment(machine_id, machine_name, mount_path, mount_mode)]
1030
1097
  # mount_mode is "ro" or "rw"
1031
1098
  ```
@@ -1084,7 +1151,9 @@ boxd.orgs.clear_domain("acme")
1084
1151
 
1085
1152
  `set_domain` starts verification immediately — call it only once NS
1086
1153
  delegation is actually live, for the same reason as per-machine domains
1087
- above. A background check then verifies delegation and issues certs
1154
+ above. An org has at most one domain in each region: `region=` picks which
1155
+ (default: the client's region), and the domain is delegated to that region's
1156
+ nameservers. A background check then verifies delegation and issues certs
1088
1157
  automatically, then flips `status` to `"active"`.
1089
1158
 
1090
1159
  An org also has a default machine size: what a `create` that names no size
@@ -1246,7 +1315,8 @@ from boxd import (
1246
1315
  BoxdError, # base class — catch this to catch everything
1247
1316
  AuthenticationError, # no usable credential, or it was rejected
1248
1317
  PermissionDeniedError, # authenticated, but not allowed
1249
- NotFoundError,
1318
+ RegionNotEnabledError, # a PermissionDeniedError: the org can't use that region yet
1319
+ NotFoundError, # .elsewhere / .close: the name in other regions
1250
1320
  ConflictError, # already exists, fights the current state, or it changed meanwhile
1251
1321
  RateLimitError, # rate limit or quota
1252
1322
  APIStatusError, # any other error from the server
@@ -40,6 +40,7 @@ Resources return plain data — a `Machine` has fields, not methods.
40
40
  ```python
41
41
  Boxd() # production
42
42
  Boxd(api_key="bxd_...")
43
+ Boxd(region="nyc") # machines in another region
43
44
  Boxd(base_url="https://boxd.example.com:9443") # any other cluster
44
45
  ```
45
46
 
@@ -50,6 +51,7 @@ Every argument is keyword-only.
50
51
  | `api_key` | `BOXD_API_KEY` | — |
51
52
  | `token` | `BOXD_TOKEN` | — |
52
53
  | `base_url` | `BOXD_BASE_URL` (or the deprecated `BOXD_API_URL`) | `https://boxd.sh:9443` |
54
+ | `region` | `BOXD_REGION` | the region `base_url` serves — see [Regions](#regions) |
53
55
  | `timeout` | — | 60.0 seconds |
54
56
  | `max_retries` | — | 2 |
55
57
 
@@ -146,6 +148,68 @@ an async generator you drive with `async for`.
146
148
  Use `AsyncBoxd` when you already have an event loop (FastAPI, asyncio scripts,
147
149
  anyio). Use `Boxd` everywhere else — scripts, notebooks, Django views.
148
150
 
151
+ ## Regions
152
+
153
+ boxd runs in several regions, each with its own API. A machine, snapshot or
154
+ disk lives in one region. Your account, organizations, API keys, environment
155
+ variables and billing live in your home region and work in every region with
156
+ the same credential.
157
+
158
+ Pick a region for the client, or for one call:
159
+
160
+ ```python
161
+ boxd = Boxd(region="nyc") # or set BOXD_REGION=nyc
162
+ boxd.machines.create("api") # created in nyc
163
+ boxd.machines.get("api") # looked up in nyc
164
+ boxd.machines.get("web", region="fra") # this call only
165
+ boxd.region # "nyc"
166
+ ```
167
+
168
+ With no region, every call goes to `base_url`, as before. Every method on
169
+ machines (and `files`, `fs`, `ports`, `proxies`, `checkpoints`, `backups`),
170
+ snapshots, disks, custom domains and org domains takes `region=`. Account and
171
+ organization calls always go to `base_url`.
172
+
173
+ ```python
174
+ for r in boxd.regions.list():
175
+ r.id, r.name, r.home, r.org_state # "enabled" | "requested" | "available"
176
+
177
+ machines = boxd.machines.list() # the client's region
178
+ machines.elsewhere # [RegionCount(region="fra", count=3)]
179
+ everywhere = boxd.machines.list(region="all")
180
+ [(m.name, m.region) for m in everywhere]
181
+ everywhere.unavailable # regions that could not be reached just now
182
+ ```
183
+
184
+ `snapshots.list()` and `disks.list()` take `region="all"` and carry
185
+ `elsewhere` too. `machine.region`, `snapshot.region` and `disk.region` say
186
+ where each one lives.
187
+
188
+ An organization can use its home region and the regions enabled for it.
189
+ Creating or listing machines or snapshots in any other region raises
190
+ `RegionNotEnabledError`. An org admin can ask for one:
191
+
192
+ ```python
193
+ boxd.orgs.regions("acme") # where the org stands with each region
194
+ boxd.orgs.request_region("nyc", "acme") # "requested", or "enabled" if it has it
195
+ boxd.orgs.set_default_region("nyc", "acme") # recorded for the org; the SDK
196
+ boxd.orgs.get_default_region("acme") # does not route by it
197
+ boxd.orgs.clear_default_region("acme")
198
+ ```
199
+
200
+ When a machine, snapshot or disk is not in the region a call went to, the SDK
201
+ asks where else your organizations have that name, and the `NotFoundError`
202
+ says so:
203
+
204
+ ```python
205
+ try:
206
+ boxd.machines.get("web")
207
+ except NotFoundError as e:
208
+ print(e) # ...; there is a machine "web" in fra: pass region="fra"
209
+ e.elsewhere # [ElsewhereItem(region="fra", name="web", org_id=..., id=...)]
210
+ e.close # names one or two letters off, in other regions
211
+ ```
212
+
149
213
  ## Machines
150
214
 
151
215
  ```python
@@ -611,6 +675,7 @@ machine.source.name # source machine, or snapshot name
611
675
  machine.source.version # int | None — snapshots only; a fork has none
612
676
  machine.source.id # str | None — provenance; may not resolve
613
677
 
678
+ machine.region # str | None — where it lives; None when boxd runs in one region
614
679
  machine.hibernated_at # datetime | None — None = not hibernated
615
680
  machine.last_connected_at # datetime | None — None = never connected
616
681
  machine.boot_time_ms # int | None — last boot; None = never booted
@@ -986,11 +1051,13 @@ snapshot.memory_bytes
986
1051
  snapshot.use_count # machines restored from it so far
987
1052
  snapshot.storage # "local" | "archiving" | "archived" | "unarchiving"
988
1053
  snapshot.archived # True unless storage is "local": machines can't be created from it
1054
+ snapshot.region # str | None — where it lives
989
1055
 
990
1056
  volume = boxd.disks.list()[0]
991
1057
  volume.id, volume.name, volume.size_bytes
992
1058
  volume.status # "creating" | "ready" | "destroyed" — attach once "ready"
993
1059
  volume.created_at # datetime | None
1060
+ volume.region # str | None — where it lives
994
1061
  volume.attachments # [DiskAttachment(machine_id, machine_name, mount_path, mount_mode)]
995
1062
  # mount_mode is "ro" or "rw"
996
1063
  ```
@@ -1049,7 +1116,9 @@ boxd.orgs.clear_domain("acme")
1049
1116
 
1050
1117
  `set_domain` starts verification immediately — call it only once NS
1051
1118
  delegation is actually live, for the same reason as per-machine domains
1052
- above. A background check then verifies delegation and issues certs
1119
+ above. An org has at most one domain in each region: `region=` picks which
1120
+ (default: the client's region), and the domain is delegated to that region's
1121
+ nameservers. A background check then verifies delegation and issues certs
1053
1122
  automatically, then flips `status` to `"active"`.
1054
1123
 
1055
1124
  An org also has a default machine size: what a `create` that names no size
@@ -1211,7 +1280,8 @@ from boxd import (
1211
1280
  BoxdError, # base class — catch this to catch everything
1212
1281
  AuthenticationError, # no usable credential, or it was rejected
1213
1282
  PermissionDeniedError, # authenticated, but not allowed
1214
- NotFoundError,
1283
+ RegionNotEnabledError, # a PermissionDeniedError: the org can't use that region yet
1284
+ NotFoundError, # .elsewhere / .close: the name in other regions
1215
1285
  ConflictError, # already exists, fights the current state, or it changed meanwhile
1216
1286
  RateLimitError, # rate limit or quota
1217
1287
  APIStatusError, # any other error from the server
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "boxd"
3
- version = "0.2.22.dev936"
3
+ version = "0.3.0"
4
4
  description = "Python SDK for the boxd cloud VM platform"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -36,6 +36,7 @@ from .errors import (
36
36
  NotFoundError,
37
37
  PermissionDeniedError,
38
38
  RateLimitError,
39
+ RegionNotEnabledError,
39
40
  )
40
41
  from .models import (
41
42
  Account,
@@ -57,6 +58,7 @@ from .models import (
57
58
  DirListing,
58
59
  DiskAttachment,
59
60
  DiskStatus,
61
+ ElsewhereItem,
60
62
  EnvVar,
61
63
  FsEntry,
62
64
  FsEntryType,
@@ -100,6 +102,10 @@ from .models import (
100
102
  Proxy,
101
103
  ProxyEntry,
102
104
  ProxyPortMode,
105
+ Region,
106
+ RegionalList,
107
+ RegionCount,
108
+ RegionOrgState,
103
109
  ResizeResult,
104
110
  ResumeResult,
105
111
  Secret,
@@ -170,6 +176,7 @@ __all__ = [
170
176
  "DirListing",
171
177
  "DiskAttachment",
172
178
  "DiskStatus",
179
+ "ElsewhereItem",
173
180
  "EnvVar",
174
181
  "ExecResult",
175
182
  "FsEntry",
@@ -213,6 +220,10 @@ __all__ = [
213
220
  "Proxy",
214
221
  "ProxyEntry",
215
222
  "ProxyPortMode",
223
+ "Region",
224
+ "RegionalList",
225
+ "RegionCount",
226
+ "RegionOrgState",
216
227
  "ResizeResult",
217
228
  "ResumeResult",
218
229
  "Secret",
@@ -260,6 +271,7 @@ __all__ = [
260
271
  "NotFoundError",
261
272
  "PermissionDeniedError",
262
273
  "RateLimitError",
274
+ "RegionNotEnabledError",
263
275
  # Version
264
276
  "__version__",
265
277
  ]
@@ -8,6 +8,7 @@ namespace returns is plain data.
8
8
  from __future__ import annotations
9
9
 
10
10
  from ._credentials import AsyncCredentials, SyncCredentials
11
+ from ._regions import AsyncRouter, SyncRouter
11
12
  from ._transport import AsyncTransport, SyncTransport
12
13
  from ._urls import DEFAULT_BASE_URL, exchange_url_for, resolve_base_url
13
14
  from .resources.account import Account, AsyncAccount
@@ -16,6 +17,7 @@ from .resources.disks import AsyncDisks, Disks
16
17
  from .resources.domains import AsyncDomains, Domains
17
18
  from .resources.machines import AsyncMachines, Machines
18
19
  from .resources.orgs import AsyncOrgs, Orgs
20
+ from .resources.regions import AsyncRegions, Regions
19
21
  from .resources.snapshots import AsyncSnapshots, Snapshots
20
22
  from .resources.teams import AsyncTeams, Teams
21
23
  from .resources.vars import AsyncEnv, AsyncSecrets, Env, Secrets
@@ -31,6 +33,7 @@ class Boxd:
31
33
 
32
34
  boxd = Boxd() # production
33
35
  boxd = Boxd(api_key="bxd_...")
36
+ boxd = Boxd(region="nyc") # machines in New York
34
37
  boxd = Boxd(base_url="https://boxd.example.com:9443") # any other cluster
35
38
 
36
39
  Args:
@@ -40,6 +43,11 @@ class Boxd:
40
43
  base_url: The cluster to talk to. Defaults to `BOXD_BASE_URL`, then
41
44
  production. There is no `environment` argument — one URL selects
42
45
  a cluster and everything else follows from it.
46
+ region: The region machines, snapshots and disks are created in and
47
+ looked up in (``"fra"``, ``"nyc"``, ...). Defaults to
48
+ `BOXD_REGION`, then the region `base_url` serves. Account and org
49
+ calls always go to `base_url`. Every such method also takes its
50
+ own ``region=``.
43
51
  timeout: Per-request timeout in seconds.
44
52
  max_retries: Retries for connection failures, with exponential backoff.
45
53
 
@@ -53,6 +61,7 @@ class Boxd:
53
61
  api_key: str | None = None,
54
62
  token: str | None = None,
55
63
  base_url: str | None = None,
64
+ region: str | None = None,
56
65
  timeout: float = DEFAULT_TIMEOUT_SECS,
57
66
  max_retries: int = DEFAULT_MAX_RETRIES,
58
67
  ) -> None:
@@ -62,11 +71,19 @@ class Boxd:
62
71
  token=token,
63
72
  exchange_url=exchange_url_for(resolved or DEFAULT_BASE_URL),
64
73
  )
65
- self._transport = SyncTransport(
66
- base_url=resolved,
67
- credentials=credentials,
68
- timeout=timeout,
69
- max_retries=max_retries,
74
+
75
+ def connect(url: str | None, *, derived: bool = False) -> SyncTransport:
76
+ # Every region's endpoint, and home's, share the one credential.
77
+ return SyncTransport(
78
+ base_url=url,
79
+ credentials=credentials,
80
+ timeout=timeout,
81
+ max_retries=max_retries,
82
+ derived=derived,
83
+ )
84
+
85
+ self._transport = SyncRouter(
86
+ connect(resolved), region=region, connect=connect, credentials=credentials
70
87
  )
71
88
 
72
89
  self.machines = Machines(self._transport)
@@ -79,12 +96,19 @@ class Boxd:
79
96
  self.teams = Teams(self._transport)
80
97
  self.api_keys = ApiKeys(self._transport)
81
98
  self.account = Account(self._transport)
99
+ self.regions = Regions(self._transport)
82
100
 
83
101
  @property
84
102
  def base_url(self) -> str:
85
- """The cluster this client talks to."""
103
+ """The cluster this client talks to: its home."""
86
104
  return self._transport.base_url
87
105
 
106
+ @property
107
+ def region(self) -> str | None:
108
+ """The client's region (``region=`` or `BOXD_REGION`); None = the
109
+ region `base_url` serves."""
110
+ return self._transport.region
111
+
88
112
  def close(self) -> None:
89
113
  """Close the underlying connection. Safe to call more than once."""
90
114
  self._transport.close()
@@ -111,6 +135,7 @@ class AsyncBoxd:
111
135
  api_key: str | None = None,
112
136
  token: str | None = None,
113
137
  base_url: str | None = None,
138
+ region: str | None = None,
114
139
  timeout: float = DEFAULT_TIMEOUT_SECS,
115
140
  max_retries: int = DEFAULT_MAX_RETRIES,
116
141
  ) -> None:
@@ -120,11 +145,19 @@ class AsyncBoxd:
120
145
  token=token,
121
146
  exchange_url=exchange_url_for(resolved or DEFAULT_BASE_URL),
122
147
  )
123
- self._transport = AsyncTransport(
124
- base_url=resolved,
125
- credentials=credentials,
126
- timeout=timeout,
127
- max_retries=max_retries,
148
+
149
+ def connect(url: str | None, *, derived: bool = False) -> AsyncTransport:
150
+ # Every region's endpoint, and home's, share the one credential.
151
+ return AsyncTransport(
152
+ base_url=url,
153
+ credentials=credentials,
154
+ timeout=timeout,
155
+ max_retries=max_retries,
156
+ derived=derived,
157
+ )
158
+
159
+ self._transport = AsyncRouter(
160
+ connect(resolved), region=region, connect=connect, credentials=credentials
128
161
  )
129
162
 
130
163
  self.machines = AsyncMachines(self._transport)
@@ -137,12 +170,19 @@ class AsyncBoxd:
137
170
  self.teams = AsyncTeams(self._transport)
138
171
  self.api_keys = AsyncApiKeys(self._transport)
139
172
  self.account = AsyncAccount(self._transport)
173
+ self.regions = AsyncRegions(self._transport)
140
174
 
141
175
  @property
142
176
  def base_url(self) -> str:
143
- """The cluster this client talks to."""
177
+ """The cluster this client talks to: its home."""
144
178
  return self._transport.base_url
145
179
 
180
+ @property
181
+ def region(self) -> str | None:
182
+ """The client's region (``region=`` or `BOXD_REGION`); None = the
183
+ region `base_url` serves."""
184
+ return self._transport.region
185
+
146
186
  async def close(self) -> None:
147
187
  """Close the underlying connection. Safe to call more than once."""
148
188
  await self._transport.close()
@@ -1,13 +1,15 @@
1
- """Credential resolution: explicit token, API-key exchange, or in-VM metadata.
1
+ """Credential resolution: explicit token, API key, or in-VM metadata.
2
2
 
3
- The gRPC API accepts exactly one credential — ``Authorization: Bearer <JWT>``.
4
- A ``bxd_`` key is never sent to :9443. Everything here exists to obtain a JWT
5
- and keep it fresh.
3
+ The gRPC API takes ``Authorization: Bearer <JWT>``, and a ``bxd_`` API key as
4
+ the bearer itself. A key goes as itself over TLS, or to a loopback address
5
+ (:meth:`_CredentialsBase.raw_key`); otherwise, and once a server refuses it as
6
+ one from before raw keys does (the transport's ``_refuses_raw_key``), it is
7
+ exchanged for a JWT that is kept fresh, as every client did before.
6
8
 
7
9
  Resolution order, first match wins:
8
10
 
9
11
  1. explicit ``token`` — used as-is, never refreshed
10
- 2. explicit ``api_key`` — exchanged for a JWT
12
+ 2. explicit ``api_key`` — sent as itself, or exchanged for a JWT
11
13
  3. ``BOXD_TOKEN``, then ``BOXD_API_KEY`` — same handling
12
14
  4. in-VM metadata adapter — no credentials required
13
15
  5. otherwise :class:`AuthenticationError` (reason ``"missing_credentials"``)
@@ -289,6 +291,24 @@ class _CredentialsBase:
289
291
  self._expires_at: float = 0.0
290
292
  # Base URL learned from the metadata adapter (in-VM mode only).
291
293
  self.discovered_base_url: str | None = None
294
+ # A server refused the key itself as an older one does: exchange it
295
+ # from now on, for the life of the client, every endpoint included.
296
+ self._raw_key_refused = False
297
+
298
+ def raw_key(self, *, allowed: bool) -> str | None:
299
+ """The API key, when a call should carry it as the bearer itself.
300
+
301
+ ``allowed`` says the endpoint is reached over TLS or on a loopback
302
+ address. ``None`` means use :meth:`token` (a token, an in-VM
303
+ credential, or the session exchanged for the key).
304
+ """
305
+ if self.mode != "exchange" or not allowed or self._raw_key_refused:
306
+ return None
307
+ return self._api_key
308
+
309
+ def raw_key_refused(self) -> None:
310
+ """A server refused the key itself: exchange it from now on."""
311
+ self._raw_key_refused = True
292
312
 
293
313
  @property
294
314
  def mode(self) -> str: