formist-cli 0.1.0__py3-none-any.whl

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.
formist_cli/api.py ADDED
@@ -0,0 +1,1027 @@
1
+ """Stdlib HTTP client for the Evane/Formist admin API, with errors an operator can act on.
2
+
3
+ This tool must add no runtime dependency, so this is ``urllib`` rather
4
+ than ``httpx``.
5
+
6
+ The value here is not the transport, it is the failure translation.
7
+ Three of the statuses this surface returns are routinely misread:
8
+
9
+ **410** is not "gone". ``/auth`` and ``/admin`` are served from the
10
+ Global region only, and the region gate installs only on non-Global
11
+ instances. So a 410 means "you pointed an admin call at ``ae``", and
12
+ the fix is to call Global, which already reads the AE database
13
+ cross-region. Space-scoped admin data is not per-region.
14
+
15
+ **404** on this API does not always mean the path is wrong: a route
16
+ can exist in the codebase and not be in the deployed image, and it
17
+ then 404s in prod while working locally. The message names both
18
+ possibilities and points at ``fm instance``, which measures the
19
+ deployed build rather than guessing at it.
20
+
21
+ **401** means the stored session is missing or stale, not that the
22
+ endpoint is protected in some new way.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import contextlib
28
+ import json
29
+ import urllib.error
30
+ import urllib.parse
31
+ import urllib.request
32
+ import uuid
33
+ from collections.abc import Iterator
34
+
35
+ from formist_cli.targets import Target, check_api_base, is_admin_env
36
+
37
+ DEFAULT_TIMEOUT = 30
38
+
39
+ #: Timeout for an upload. Separate from :data:`DEFAULT_TIMEOUT` because a
40
+ #: whole-workspace bundle is megabytes and would otherwise fail on size
41
+ #: while reporting a timeout, i.e. the wrong cause attached to a real
42
+ #: failure.
43
+ UPLOAD_TIMEOUT = 600
44
+
45
+
46
+ class ApiError(Exception):
47
+ """An API call that failed, phrased for whoever has to fix it."""
48
+
49
+ def __init__(self, message: str, *, status: int | None = None):
50
+ super().__init__(message)
51
+ #: The HTTP status behind this, when there was one (``None`` for
52
+ #: a transport failure, or for a refusal this tool made before
53
+ #: sending anything).
54
+ #:
55
+ #: Carried as a number on purpose, so a caller that needs to
56
+ #: branch on the status does not have to read it back out of
57
+ #: the message text.
58
+ self.status = status
59
+
60
+
61
+ class NotAuthenticated(ApiError):
62
+ pass
63
+
64
+
65
+ class StreamClosed(ApiError):
66
+ """A stream that was open and is not any more.
67
+
68
+ Its own class because the caller must be able to tell it apart
69
+ from "the stream was quiet". Both look identical at the terminal,
70
+ an iterator that stopped yielding, and only one of them means the
71
+ caller is no longer being told anything.
72
+ """
73
+
74
+
75
+ def _build_request(
76
+ target: Target,
77
+ path: str,
78
+ *,
79
+ token: str | None,
80
+ params: dict[str, str] | None,
81
+ accept: str | None = None,
82
+ method: str = "GET",
83
+ data: bytes | None = None,
84
+ content_type: str | None = None,
85
+ ) -> urllib.request.Request:
86
+ """The one place a request to this API is constructed.
87
+
88
+ Extracted rather than copied because :func:`get`, :func:`download`
89
+ and :func:`stream` differ only in how they consume the response:
90
+ same host check, same param encoding, same credential placement.
91
+
92
+ ``check_api_base`` runs first and before any socket is opened, so
93
+ an unknown host is refused rather than tried.
94
+
95
+ The credential goes in the ``Authorization`` header, never the
96
+ query string, so a client that helpfully added a token query
97
+ parameter cannot leak it into a URL that might be logged.
98
+
99
+ ``method``/``data``/``content_type`` exist for :func:`stream_post`,
100
+ the one other caller on this shared path that needs a request body
101
+ (a streaming GET has none). :func:`get`, :func:`download` and
102
+ :func:`stream` never pass them.
103
+ """
104
+ check_api_base(target.api_base)
105
+
106
+ url = f"{target.api_base}{path}"
107
+ if params:
108
+ url = f"{url}?{urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})}"
109
+
110
+ request = urllib.request.Request(url, data=data, method=method)
111
+ if accept:
112
+ request.add_header("Accept", accept)
113
+ if content_type:
114
+ request.add_header("Content-Type", content_type)
115
+ if token:
116
+ # Bearer, not a cookie: the server accepts either, and a header
117
+ # keeps the credential out of any URL that might be logged.
118
+ request.add_header("Authorization", f"Bearer {token}")
119
+ return request
120
+
121
+
122
+ def get(
123
+ target: Target,
124
+ path: str,
125
+ *,
126
+ token: str | None = None,
127
+ params: dict[str, str] | None = None,
128
+ timeout: int = DEFAULT_TIMEOUT,
129
+ ) -> object:
130
+ """GET ``path`` from ``target`` and return the decoded JSON body."""
131
+ request = _build_request(target, path, token=token, params=params, accept="application/json")
132
+
133
+ try:
134
+ with urllib.request.urlopen(request, timeout=timeout) as response:
135
+ body = response.read().decode()
136
+ except urllib.error.HTTPError as exc:
137
+ raise _translate(exc, target, path) from None
138
+ except urllib.error.URLError as exc:
139
+ raise ApiError(_unreachable(target, exc)) from None
140
+
141
+ if not body:
142
+ return None
143
+ try:
144
+ return json.loads(body)
145
+ except json.JSONDecodeError:
146
+ return body
147
+
148
+
149
+ def download(
150
+ target: Target,
151
+ path: str,
152
+ *,
153
+ token: str | None = None,
154
+ params: dict[str, str] | None = None,
155
+ timeout: int = DEFAULT_TIMEOUT,
156
+ ) -> tuple[bytes, str | None]:
157
+ """GET ``path`` as raw bytes plus its ``Content-Disposition``.
158
+
159
+ Separate from :func:`get` because an export is not JSON in either
160
+ direction: a bundle ZIP cannot survive ``json.loads``, and even a
161
+ JSON bundle should land on disk as the server serialized it rather
162
+ than as this process would re-serialize it. Round-tripping through
163
+ a dict and back would change key order and whitespace, so the file
164
+ would no longer be the bytes the server sent, which is precisely
165
+ what a portability export is for.
166
+
167
+ The header comes back rather than the filename, because parsing it
168
+ is the caller's business: a server-supplied filename must not
169
+ choose a path.
170
+ """
171
+ request = _build_request(target, path, token=token, params=params)
172
+
173
+ try:
174
+ with urllib.request.urlopen(request, timeout=timeout) as response:
175
+ return response.read(), response.headers.get("Content-Disposition")
176
+ except urllib.error.HTTPError as exc:
177
+ raise _translate(exc, target, path) from None
178
+ except urllib.error.URLError as exc:
179
+ raise ApiError(_unreachable(target, exc)) from None
180
+
181
+
182
+ def _open_stream(
183
+ request: urllib.request.Request, target: Target, path: str, read_timeout: float
184
+ ):
185
+ """``urlopen`` a streaming request, translating a failure to open it.
186
+
187
+ Shared by :func:`stream` and :func:`stream_post`: the two build a
188
+ different request (GET vs POST+body), but what a failure to even
189
+ open the socket means is identical.
190
+ """
191
+ try:
192
+ return urllib.request.urlopen(request, timeout=read_timeout)
193
+ except urllib.error.HTTPError as exc:
194
+ raise _translate(exc, target, path) from None
195
+ except urllib.error.URLError as exc:
196
+ raise ApiError(_unreachable(target, exc)) from None
197
+
198
+
199
+ def _stream_lines(response, target: Target) -> Iterator[str]:
200
+ """Decode an already-open response into lines, one at a time.
201
+
202
+ Raises :class:`StreamClosed` on a mid-stream drop rather than
203
+ letting the iterator simply stop: the alternative would render a
204
+ dropped connection as a quiet one, which is the failure both
205
+ :func:`stream` and :func:`stream_post` exist to make impossible.
206
+ """
207
+ try:
208
+ for raw in response:
209
+ yield raw.decode("utf-8", errors="replace").rstrip("\r\n")
210
+ except (TimeoutError, OSError) as exc:
211
+ # Not a normal end. A read timeout means the keepalive (or, for
212
+ # stream_post, the operator's read_timeout) we sized this against did
213
+ # not arrive, which is a dropped connection wearing a quiet stream's
214
+ # clothes.
215
+ raise StreamClosed(
216
+ f"the stream to {target.name} stopped mid-connection ({exc}).\n"
217
+ "This is NOT the same as 'nothing happened': the server went away "
218
+ "or the network did, and events emitted from now on are lost.\n"
219
+ "Re-run to reconnect. There is no replay: the bus is in-process "
220
+ "and nothing buffers for a disconnected subscriber."
221
+ ) from None
222
+
223
+
224
+ @contextlib.contextmanager
225
+ def stream(
226
+ target: Target,
227
+ path: str,
228
+ *,
229
+ token: str | None = None,
230
+ params: dict[str, str] | None = None,
231
+ read_timeout: float,
232
+ ) -> Iterator[Iterator[str]]:
233
+ """Open a long-lived GET and yield decoded lines as the server writes them.
234
+
235
+ A third consumer of :func:`_build_request`, not a second transport.
236
+ Everything up to ``urlopen`` is shared with :func:`get` and
237
+ :func:`download`; what differs is that the response is not read to
238
+ completion (a firehose has no completion), so the socket stays open
239
+ and the caller iterates.
240
+
241
+ That single difference is why this cannot simply be ``download`` in
242
+ a loop: ``download`` calls ``response.read()``, which by definition
243
+ returns when the body ends, and this body is not supposed to end.
244
+
245
+ ``read_timeout`` is required and has no default. It is the only
246
+ thing that can tell a live-but-idle stream from a dead socket, and
247
+ the two are otherwise indistinguishable: both are a file object
248
+ that yields nothing. A default here would be a number picked
249
+ without knowing the server's keepalive period, which is the one
250
+ fact that makes the distinction possible, so the caller, which
251
+ does know it, must state it.
252
+
253
+ Raises :class:`StreamClosed` when the connection drops mid-stream,
254
+ rather than letting the iterator simply stop and render a dropped
255
+ connection as a quiet one.
256
+ """
257
+ request = _build_request(target, path, token=token, params=params)
258
+ response = _open_stream(request, target, path, read_timeout)
259
+ try:
260
+ yield _stream_lines(response, target)
261
+ finally:
262
+ response.close()
263
+
264
+
265
+ @contextlib.contextmanager
266
+ def stream_post(
267
+ target: Target,
268
+ path: str,
269
+ body: object,
270
+ *,
271
+ token: str | None = None,
272
+ params: dict[str, str] | None = None,
273
+ read_timeout: float,
274
+ ) -> Iterator[Iterator[str]]:
275
+ """Open a long-lived POST carrying a JSON body and yield decoded lines.
276
+
277
+ :func:`stream` cannot serve an endpoint whose turn text has to
278
+ travel in the request body, since ``stream``'s request is GET-only
279
+ by construction. This is that same transport for a POST: same host
280
+ allow-list (:func:`_build_request`), same "a drop is not a quiet
281
+ stream" guarantee (:class:`StreamClosed`, via :func:`_stream_lines`),
282
+ same required ``read_timeout`` and for the same reason.
283
+
284
+ The body is JSON-encoded here rather than accepted pre-encoded,
285
+ matching :func:`post`, since this tool has one write encoding, not
286
+ one per caller.
287
+ """
288
+ request = _build_request(
289
+ target,
290
+ path,
291
+ token=token,
292
+ params=params,
293
+ accept="text/event-stream",
294
+ method="POST",
295
+ data=json.dumps(body).encode(),
296
+ content_type="application/json",
297
+ )
298
+ response = _open_stream(request, target, path, read_timeout)
299
+ try:
300
+ yield _stream_lines(response, target)
301
+ finally:
302
+ response.close()
303
+
304
+
305
+ def _translate(exc: urllib.error.HTTPError, target: Target, path: str) -> ApiError:
306
+ """Translate, then stamp the status on whatever came back.
307
+
308
+ Stamping here rather than at each ``return`` is deliberate: this
309
+ function has several branches, and a per-branch ``status=`` is a
310
+ thing to remember. Setting it once on the way out cannot miss one.
311
+ """
312
+ error = _translated(exc, target, path)
313
+ error.status = exc.code
314
+ return error
315
+
316
+
317
+ #: The refusal a CLI credential gets when its account is a platform admin
318
+ #: but this particular credential was not granted the admin scope.
319
+ #: Unlike the two ``platform-admin-required`` messages below, which
320
+ #: describe the same gate from a GET and a POST, this one is a single
321
+ #: function called from both branches: the answer does not depend on
322
+ #: the method, so there is nothing for a second copy to say.
323
+ #:
324
+ #: It deliberately offers no way around the refusal beyond
325
+ #: re-authorizing, because there is none: the server checks the scope
326
+ #: on every call and the CLI holds no credential that could bypass it.
327
+ def _cli_scope_refusal(target: Target, detail: str | None) -> ApiError:
328
+ return ApiError(
329
+ f"403 from {target.name}: {detail or 'this credential lacks the admin scope'}\n"
330
+ "Your account may well be a platform admin; this particular `fm` "
331
+ "credential was not granted platform-admin access when you authorized it.\n"
332
+ f"Run `fm login --host {target.name}` again and tick 'Also allow platform-admin "
333
+ "actions' on the authorization page. The box is only shown to platform "
334
+ "admins, and the server re-checks both facts on every call."
335
+ )
336
+
337
+
338
+ def _translated(exc: urllib.error.HTTPError, target: Target, path: str) -> ApiError:
339
+ try:
340
+ payload = json.loads(exc.read().decode())
341
+ except Exception:
342
+ payload = {}
343
+ code = payload.get("error") if isinstance(payload, dict) else None
344
+ detail = payload.get("message") if isinstance(payload, dict) else None
345
+
346
+ if exc.code == 410 or code == "auth-not-served-in-region":
347
+ return ApiError(
348
+ f"410 from {target.name}: {path} is served from the GLOBAL region only.\n"
349
+ "The /auth and /admin surfaces are Global-only; the region gate runs on "
350
+ "the non-Global instances.\n"
351
+ "Retry with `--host evane`. You do NOT lose AE data by doing so: the "
352
+ "Global admin API reads the AE database cross-region, so space-scoped "
353
+ "admin data is not per-region."
354
+ )
355
+
356
+ if exc.code == 404:
357
+ # Sibling: `_translated_body`'s 404 branch answers for the exact
358
+ # same ambiguity on the write path. If you change one, change the
359
+ # other.
360
+ #
361
+ # A domain 404 (space/user/chat/skill/invitation not found) carries
362
+ # a structured `{"error": ..., "message": ...}` body; a route that
363
+ # was never registered answers `{"detail": "Not Found"}`, which has
364
+ # no `error` key. `code` tells the two apart, so a typo'd id gets
365
+ # the real reason instead of a prompt to go compare build
366
+ # revisions for something that was never a deploy gap.
367
+ if code:
368
+ return ApiError(f"404 from {target.name} on {path}: {detail or code}")
369
+ return ApiError(
370
+ f"404 from {target.name}: {path} is not served there.\n"
371
+ "Two different things look identical here and fm cannot tell them "
372
+ "apart: the path may be wrong, or it may be right and simply not in "
373
+ "the image this region is running.\n"
374
+ f"Run `fm instance --host {target.name}` to report the deployed build "
375
+ "and migration revision. Compare it with the code you are holding; "
376
+ "that measures the answer, where fm could only guess it."
377
+ )
378
+
379
+ if exc.code == 401 or code == "not-authenticated":
380
+ return NotAuthenticated(
381
+ f"401 from {target.name}: no valid session.\n"
382
+ f"Run `fm login --host {target.name}` (check the current one with "
383
+ f"`fm whoami --host {target.name}`)"
384
+ )
385
+
386
+ if code == "cli-admin-scope-required":
387
+ return _cli_scope_refusal(target, detail)
388
+
389
+ if exc.code == 403 or code == "platform-admin-required":
390
+ # Sibling: `_translated_body`'s 403 branch answers for the same
391
+ # gate. If you change one of these two messages, change the other.
392
+ return ApiError(
393
+ f"403 from {target.name}: this needs User.is_platform_admin on your row.\n"
394
+ "A valid session is not enough: the flag is checked fresh on every call."
395
+ )
396
+
397
+ return ApiError(f"{exc.code} from {target.name} on {path}: {detail or code or exc.reason}")
398
+
399
+
400
+ def _unreachable(target: Target, exc: urllib.error.URLError) -> str:
401
+ if target.env == "local":
402
+ return (
403
+ f"could not reach {target.api_base} ({exc.reason}).\n"
404
+ "Is the server running on that port?"
405
+ )
406
+ return (
407
+ f"could not reach {target.api_base} ({exc.reason}).\n"
408
+ f"Check the deployment is up: `fm health --host {target.name}`."
409
+ )
410
+
411
+
412
+ #: ``/admin`` prefixes the server serves from every region, so this client
413
+ #: must not refuse them. Mirrors the routers' own region-scope
414
+ #: declaration; a local tuple rather than a live read, since importing
415
+ #: the server's routers would pull the whole server into a CLI start-up.
416
+ REGION_LOCAL_ADMIN_PREFIXES = (
417
+ "/admin/alerts",
418
+ "/admin/instance",
419
+ "/admin/messages",
420
+ "/admin/whatsapp",
421
+ )
422
+
423
+
424
+ def _is_region_local_admin(path: str) -> bool:
425
+ """Segment-aware, exactly like the server's gate: ``/admin/messages`` covers
426
+ ``/admin/messages/dedupe`` and never ``/admin/messages-export``."""
427
+ return any(
428
+ path == prefix or path.startswith(f"{prefix}/")
429
+ for prefix in REGION_LOCAL_ADMIN_PREFIXES
430
+ )
431
+
432
+
433
+ def _check_admin_target(target: Target, path: str, token: str | None) -> None:
434
+ """The two refusals every ``/admin`` call shares, in one place.
435
+
436
+ Failing here rather than at the server saves a round trip and,
437
+ more usefully, explains the topology instead of returning a status
438
+ code.
439
+
440
+ ``REGION_FORMIST`` is exempt from the Global-only gate below for a
441
+ different reason than the region-local-admin prefixes are: this
442
+ gate exists because Evane is multi-region and only Global mounts
443
+ the full ``/admin`` router. Formist is a wholly separate,
444
+ single-region deployment with no Global/AE split of its own; its
445
+ one API host serves the whole ``/admin`` surface locally, the same
446
+ as a local dev server does. Gating it behind "must be Global"
447
+ would refuse every Formist admin call outright. See
448
+ ``formist_cli.targets.is_admin_env``, the one predicate this and
449
+ the other admin-region gates share.
450
+ """
451
+ if (
452
+ target.is_prod
453
+ and not is_admin_env(target.env)
454
+ and not _is_region_local_admin(path)
455
+ ):
456
+ raise ApiError(
457
+ f"{path} is served from the GLOBAL region only; sending this to "
458
+ f"{target.name} would return 410.\n"
459
+ "Use `--host evane`. The Global admin API reads the AE database "
460
+ "cross-region, so you still see AE spaces from there."
461
+ )
462
+ if not token:
463
+ # A library-layer guard: this module can be imported directly by a
464
+ # script that never came through the CLI, so it cannot assume the
465
+ # CLI resolver ran. The CLI's own resolver raises the same refusal
466
+ # earlier for callers that did. Both exist deliberately: neither is
467
+ # dead, each covers a caller the other cannot see.
468
+ raise NotAuthenticated(
469
+ f"no stored session for {target.name}. Run `fm login --host {target.name}`"
470
+ )
471
+
472
+
473
+ def admin_get(target: Target, path: str, *, token: str | None, **kwargs) -> object:
474
+ """GET an ``/admin`` path, refusing up front to send it to a gated region."""
475
+ _check_admin_target(target, path, token)
476
+ return get(target, path, token=token, **kwargs)
477
+
478
+
479
+ def admin_put(target: Target, path: str, body: object, *, token: str | None) -> object:
480
+ """PUT JSON to an ``/admin`` path, behind the same two refusals as the GET.
481
+
482
+ This sends a write to whatever ``target`` names, so the caller must
483
+ have resolved ``--env`` from the command line and never from
484
+ ``fm use``. The one write on this surface today is
485
+ ``PUT /admin/spaces/{id}/plan``, which is itself a dry run unless
486
+ the body says ``apply: true``.
487
+ """
488
+ _check_admin_target(target, path, token)
489
+ return put(target, path, body, token=token)
490
+
491
+
492
+ def admin_put_multipart(
493
+ target: Target,
494
+ path: str,
495
+ *,
496
+ fields: dict[str, str],
497
+ files: dict[str, tuple[str, bytes]],
498
+ token: str | None,
499
+ ) -> object:
500
+ """PUT ``multipart/form-data`` to an ``/admin`` path, behind the same two
501
+ refusals as the GET.
502
+
503
+ Same caveat as :func:`admin_put`: this is a write, so the caller
504
+ must have resolved ``--env`` from the command line and never from
505
+ ``fm use``. The one caller today is ``fm skill-library-cover set``,
506
+ which takes an image as an ``UploadFile`` rather than as JSON.
507
+ """
508
+ _check_admin_target(target, path, token)
509
+ return put_multipart(target, path, fields=fields, files=files, token=token)
510
+
511
+
512
+ def admin_post(target: Target, path: str, body: object, *, token: str | None, **kwargs) -> object:
513
+ """POST JSON to an ``/admin`` path, behind the same two refusals as the GET.
514
+
515
+ Same caveat as :func:`admin_put`: this can send a write, so the
516
+ caller must have resolved ``--env`` from the command line and
517
+ never from ``fm use``. The write on this surface is
518
+ ``POST /admin/spaces/{id}/i18n/backfill``, itself a dry run unless
519
+ the body says ``dry_run: false``.
520
+
521
+ ``**kwargs`` forwards to :func:`post` (e.g. ``timeout``, for a
522
+ caller that needs longer than :data:`DEFAULT_TIMEOUT`).
523
+ """
524
+ _check_admin_target(target, path, token)
525
+ return post(target, path, body, token=token, **kwargs)
526
+
527
+
528
+ def admin_post_multipart(
529
+ target: Target,
530
+ path: str,
531
+ *,
532
+ fields: dict[str, str],
533
+ files: dict[str, tuple[str, bytes]],
534
+ token: str | None,
535
+ timeout: int = UPLOAD_TIMEOUT,
536
+ ) -> object:
537
+ """POST ``multipart/form-data`` to an ``/admin`` path, behind the same two
538
+ refusals as :func:`admin_get`.
539
+
540
+ The roster import/reconcile endpoints are the first ``/admin``
541
+ writes that take an uploaded file rather than a JSON body; every
542
+ other admin write sends JSON. Behind the identical
543
+ ``_check_admin_target`` guard as every other ``admin_*`` function;
544
+ only the encoding differs, same relationship :func:`post_multipart`
545
+ has to :func:`post`.
546
+ """
547
+ _check_admin_target(target, path, token)
548
+ return post_multipart(target, path, fields=fields, files=files, token=token, timeout=timeout)
549
+
550
+
551
+ def admin_post_download(
552
+ target: Target, path: str, *, token: str | None, timeout: int = UPLOAD_TIMEOUT
553
+ ) -> bytes:
554
+ """POST (empty body) to an ``/admin`` path and return the raw response bytes.
555
+
556
+ For an operator export that the server audits as an action: a zip
557
+ cannot go through :func:`_send`, which decodes the body as UTF-8
558
+ JSON. Same guard as every ``admin_*`` function.
559
+ """
560
+ _check_admin_target(target, path, token)
561
+ request = urllib.request.Request(f"{target.api_base}{path}", data=b"", method="POST")
562
+ if token:
563
+ request.add_header("Authorization", f"Bearer {token}")
564
+ try:
565
+ with urllib.request.urlopen(request, timeout=timeout) as response:
566
+ return response.read()
567
+ except urllib.error.HTTPError as exc:
568
+ raise _translate(exc, target, path) from None
569
+ except urllib.error.URLError as exc:
570
+ raise ApiError(_unreachable(target, exc)) from None
571
+
572
+
573
+ def admin_patch(target: Target, path: str, body: object, *, token: str | None) -> object:
574
+ """PATCH JSON to an ``/admin`` path, behind the same two refusals as the GET.
575
+
576
+ Same caveat as :func:`admin_put`: every call through here is a
577
+ write (``fm users set``, ``fm spaces rename``), so the caller must
578
+ have resolved ``--env`` from the command line and never from
579
+ ``fm use``.
580
+ """
581
+ _check_admin_target(target, path, token)
582
+ return patch(target, path, body, token=token)
583
+
584
+
585
+ def admin_delete(
586
+ target: Target, path: str, *, token: str | None, params: dict[str, str] | None = None
587
+ ) -> object:
588
+ """DELETE an ``/admin`` path, behind the same two refusals as the GET.
589
+
590
+ Same caveat as :func:`admin_put`: every call through here is a
591
+ write (``fm users remove-space``, ``fm spaces delete``), so the
592
+ caller must have resolved ``--env`` from the command line and never
593
+ from ``fm use``. ``params`` exists for
594
+ ``DELETE /admin/spaces/{id}?confirm=true``, the one route on this
595
+ surface that reads a query-string confirmation rather than a body.
596
+ """
597
+ _check_admin_target(target, path, token)
598
+ if params:
599
+ url_path = f"{path}?{urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})}"
600
+ else:
601
+ url_path = path
602
+ return delete(target, url_path, token=token)
603
+
604
+
605
+ class BulkRefused(ApiError):
606
+ """The bulk endpoint refused a batch and told us why, per op.
607
+
608
+ Carries the parsed report rather than a string, because the
609
+ refusal is the product here: ``refusals[].index`` names the
610
+ offending op and ``reason`` is the machine-readable code a caller
611
+ branches on.
612
+ """
613
+
614
+ def __init__(self, message: str, payload: dict):
615
+ super().__init__(message)
616
+ self.payload = payload
617
+
618
+
619
+ class Misdirected(ApiError):
620
+ """421: this space lives in another region. Never followed automatically."""
621
+
622
+ def __init__(self, message: str, retry_at: str | None):
623
+ super().__init__(message)
624
+ self.retry_at = retry_at
625
+
626
+
627
+ def _send(
628
+ target: Target,
629
+ path: str,
630
+ data: bytes,
631
+ *,
632
+ method: str,
633
+ content_type: str,
634
+ token: str | None,
635
+ timeout: int,
636
+ ) -> object:
637
+ """Send a body to ``path`` and return the decoded response.
638
+
639
+ The one place a write is transmitted to this API: :func:`post`
640
+ (JSON) and :func:`put_bytes` / :func:`patch` / :func:`delete`
641
+ differ only in how the body is encoded, not in how the request is
642
+ sent or how its errors are read.
643
+
644
+ Two statuses get their own exception rather than the generic
645
+ translation, because both carry something the operator must see:
646
+
647
+ **400 ``bulk-refused``** carries the full per-op report. Flattening
648
+ it into a message would throw away the index and reason that say
649
+ which op was wrong. Only the bulk endpoint ever answers this way,
650
+ so the check is a no-op for any other path.
651
+
652
+ **421** is the region registry saying the space lives elsewhere.
653
+ It is raised, never followed: a redirect is the server telling the
654
+ caller its belief about where was wrong, and that is the one
655
+ belief a write must not be wrong about. Following it would turn a
656
+ wrong guess into a successful write against a database the
657
+ operator did not name. This applies to any project-scoped write,
658
+ not only the bulk endpoint; a resumable-upload chunk sent to a
659
+ misresolved region can answer it too.
660
+ """
661
+ check_api_base(target.api_base)
662
+
663
+ request = urllib.request.Request(f"{target.api_base}{path}", data=data, method=method)
664
+ request.add_header("Accept", "application/json")
665
+ request.add_header("Content-Type", content_type)
666
+ if token:
667
+ request.add_header("Authorization", f"Bearer {token}")
668
+
669
+ try:
670
+ with urllib.request.urlopen(request, timeout=timeout) as response:
671
+ raw = response.read().decode()
672
+ except urllib.error.HTTPError as exc:
673
+ raw_error = exc.read().decode()
674
+ try:
675
+ payload = json.loads(raw_error)
676
+ except json.JSONDecodeError:
677
+ payload = {}
678
+
679
+ if exc.code == 400 and isinstance(payload, dict) and (
680
+ payload.get("error") == "bulk-refused" or "refusals" in payload
681
+ ):
682
+ raise BulkRefused(
683
+ f"the batch was refused by {target.name} and NOTHING was applied.",
684
+ payload,
685
+ ) from None
686
+
687
+ if exc.code == 421:
688
+ retry_at = payload.get("api_base") if isinstance(payload, dict) else None
689
+ raise Misdirected(
690
+ f"421 from {target.name}: this space is resident in another region"
691
+ + (f" ({retry_at})" if retry_at else "")
692
+ + ".\n"
693
+ "fm does not follow a region redirect into a write. A redirect means "
694
+ "your belief about WHERE was wrong, which is the one belief a write "
695
+ "must not be wrong about; following it would write a database you "
696
+ "did not name.\n"
697
+ "Re-run with the --env that owns this space, after checking "
698
+ "`fm spaces --host evane` for its region.",
699
+ retry_at,
700
+ ) from None
701
+
702
+ raise _translate_body(exc, payload, target, path) from None
703
+ except urllib.error.URLError as exc:
704
+ raise ApiError(_unreachable(target, exc)) from None
705
+
706
+ if not raw:
707
+ return None
708
+ try:
709
+ return json.loads(raw)
710
+ except json.JSONDecodeError:
711
+ return raw
712
+
713
+
714
+ def post(
715
+ target: Target,
716
+ path: str,
717
+ body: object,
718
+ *,
719
+ token: str | None = None,
720
+ timeout: int = DEFAULT_TIMEOUT,
721
+ ) -> object:
722
+ """POST JSON to ``path`` and return the decoded body. See :func:`_send`."""
723
+ return _send(
724
+ target,
725
+ path,
726
+ json.dumps(body).encode(),
727
+ method="POST",
728
+ content_type="application/json",
729
+ token=token,
730
+ timeout=timeout,
731
+ )
732
+
733
+
734
+ def encode_multipart(
735
+ fields: dict[str, str], files: dict[str, tuple[str, bytes]]
736
+ ) -> tuple[bytes, str]:
737
+ """Encode ``fields`` + ``files`` as ``multipart/form-data``.
738
+
739
+ Returns ``(body, content_type)``. Stdlib only: there is no
740
+ ``requests`` here and there must not be.
741
+
742
+ The boundary is verified absent from the body, not assumed absent.
743
+ A boundary that also occurs inside the uploaded bytes truncates the
744
+ upload at that point, and the server then receives a shorter,
745
+ structurally valid request: the failure does not raise here and
746
+ does not 400 there, it lands as a bundle missing its tail. So the
747
+ check is an assertion rather than a comment about how unlikely a
748
+ 128-bit collision is.
749
+ """
750
+ for _ in range(4):
751
+ boundary = "----evbnd" + uuid.uuid4().hex + uuid.uuid4().hex
752
+ marker = boundary.encode()
753
+ if not any(marker in blob for _, blob in files.values()):
754
+ break
755
+ else: # pragma: no cover - four independent 128-bit collisions
756
+ raise ApiError(
757
+ "could not choose a multipart boundary absent from the payload."
758
+ )
759
+
760
+ out = bytearray()
761
+ for name, value in fields.items():
762
+ out += b"--" + marker + b"\r\n"
763
+ out += f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode()
764
+ out += str(value).encode() + b"\r\n"
765
+ for name, (filename, blob) in files.items():
766
+ out += b"--" + marker + b"\r\n"
767
+ out += (
768
+ f'Content-Disposition: form-data; name="{name}"; '
769
+ f'filename="{filename}"\r\n'
770
+ ).encode()
771
+ out += b"Content-Type: application/octet-stream\r\n\r\n"
772
+ out += blob + b"\r\n"
773
+ out += b"--" + marker + b"--\r\n"
774
+ return bytes(out), f"multipart/form-data; boundary={boundary}"
775
+
776
+
777
+ def post_form(
778
+ target: Target,
779
+ path: str,
780
+ fields: dict[str, str],
781
+ *,
782
+ token: str | None = None,
783
+ timeout: int = DEFAULT_TIMEOUT,
784
+ ) -> object:
785
+ """POST ``application/x-www-form-urlencoded``: the OAuth token endpoint.
786
+
787
+ OAuth 2.1 specifies form encoding at ``/token`` (RFC 6749 section 4.1.3),
788
+ not JSON. So this cannot go through :func:`post`. It goes through
789
+ :func:`_send` like every other write, which is the point of it
790
+ being here rather than a bare ``urlopen`` inside the login flow:
791
+ the host allow-list, the 410/404/403 translation and the 421
792
+ refusal are the same code as for every other call.
793
+ """
794
+ return _send(
795
+ target,
796
+ path,
797
+ urllib.parse.urlencode(fields).encode(),
798
+ method="POST",
799
+ content_type="application/x-www-form-urlencoded",
800
+ token=token,
801
+ timeout=timeout,
802
+ )
803
+
804
+
805
+ def post_multipart(
806
+ target: Target,
807
+ path: str,
808
+ *,
809
+ fields: dict[str, str],
810
+ files: dict[str, tuple[str, bytes]],
811
+ token: str | None = None,
812
+ timeout: int = UPLOAD_TIMEOUT,
813
+ ) -> object:
814
+ """POST ``multipart/form-data`` to ``path`` and return the decoded body.
815
+
816
+ Goes through :func:`_send` like every other write, so the 421
817
+ region-redirect refusal and the ``bulk-refused`` unpacking are the
818
+ same code here as in :func:`post`, not a second spelling of them.
819
+ Only the encoding differs.
820
+
821
+ The default timeout is :data:`UPLOAD_TIMEOUT` rather than
822
+ :data:`DEFAULT_TIMEOUT`: this carries a whole-workspace archive,
823
+ and 30s is a limit the bundle would hit on size rather than on
824
+ anything being wrong.
825
+ """
826
+ data, content_type = encode_multipart(fields, files)
827
+ return _send(
828
+ target,
829
+ path,
830
+ data,
831
+ method="POST",
832
+ content_type=content_type,
833
+ token=token,
834
+ timeout=timeout,
835
+ )
836
+
837
+
838
+ def put_multipart(
839
+ target: Target,
840
+ path: str,
841
+ *,
842
+ fields: dict[str, str],
843
+ files: dict[str, tuple[str, bytes]],
844
+ token: str | None = None,
845
+ timeout: int = UPLOAD_TIMEOUT,
846
+ ) -> object:
847
+ """PUT ``multipart/form-data`` to ``path`` and return the decoded body.
848
+
849
+ The verb, and only the verb, is what separates this from
850
+ :func:`post_multipart`: same encoder, same :func:`_send`. It exists
851
+ because the server routes an image replacement as PUT (an
852
+ ``UploadFile``), so neither :func:`admin_put` (JSON) nor
853
+ :func:`put_bytes` (a raw octet-stream, for resumable-upload chunks)
854
+ can reach it.
855
+ """
856
+ data, content_type = encode_multipart(fields, files)
857
+ return _send(
858
+ target,
859
+ path,
860
+ data,
861
+ method="PUT",
862
+ content_type=content_type,
863
+ token=token,
864
+ timeout=timeout,
865
+ )
866
+
867
+
868
+ def patch(
869
+ target: Target,
870
+ path: str,
871
+ body: object,
872
+ *,
873
+ token: str | None = None,
874
+ timeout: int = DEFAULT_TIMEOUT,
875
+ ) -> object:
876
+ """PATCH JSON to ``path`` and return the decoded body. See :func:`_send`."""
877
+ return _send(
878
+ target,
879
+ path,
880
+ json.dumps(body).encode(),
881
+ method="PATCH",
882
+ content_type="application/json",
883
+ token=token,
884
+ timeout=timeout,
885
+ )
886
+
887
+
888
+ def put(
889
+ target: Target,
890
+ path: str,
891
+ body: object,
892
+ *,
893
+ token: str | None = None,
894
+ timeout: int = DEFAULT_TIMEOUT,
895
+ ) -> object:
896
+ """PUT JSON to ``path`` and return the decoded body. See :func:`_send`.
897
+
898
+ Distinct from :func:`put_bytes`, which sends an unparsed byte
899
+ stream for a resumable-upload chunk. Same verb, different content
900
+ type; keeping them as one function with a mode flag would put the
901
+ upload path and a JSON admin write on one branch, which is not a
902
+ saving worth making.
903
+ """
904
+ return _send(
905
+ target,
906
+ path,
907
+ json.dumps(body).encode(),
908
+ method="PUT",
909
+ content_type="application/json",
910
+ token=token,
911
+ timeout=timeout,
912
+ )
913
+
914
+
915
+ def delete(
916
+ target: Target,
917
+ path: str,
918
+ *,
919
+ token: str | None = None,
920
+ timeout: int = DEFAULT_TIMEOUT,
921
+ ) -> object:
922
+ """DELETE ``path`` and return the decoded body. See :func:`_send`."""
923
+ return _send(
924
+ target,
925
+ path,
926
+ b"",
927
+ method="DELETE",
928
+ content_type="application/json",
929
+ token=token,
930
+ timeout=timeout,
931
+ )
932
+
933
+
934
+ def put_bytes(
935
+ target: Target,
936
+ path: str,
937
+ data: bytes,
938
+ *,
939
+ token: str | None = None,
940
+ content_type: str = "application/octet-stream",
941
+ timeout: int = DEFAULT_TIMEOUT,
942
+ ) -> object:
943
+ """PUT raw bytes to ``path`` and return the decoded JSON body.
944
+
945
+ For a resumable-upload chunk, which reads the request body as an
946
+ unparsed byte stream, the same reason :func:`post` sends JSON
947
+ rather than multipart: no multipart/form-data encoder exists in
948
+ the stdlib, and this tool may add no runtime dependency to get
949
+ one. The chunk route takes raw bytes precisely because it does not
950
+ need one either.
951
+ """
952
+ return _send(
953
+ target,
954
+ path,
955
+ data,
956
+ method="PUT",
957
+ content_type=content_type,
958
+ token=token,
959
+ timeout=timeout,
960
+ )
961
+
962
+
963
+ def _translate_body(exc, payload: dict, target: Target, path: str) -> ApiError:
964
+ """`_translate`, for a caller that already consumed the error body."""
965
+ error = _translated_body(exc, payload, target, path)
966
+ error.status = exc.code
967
+ return error
968
+
969
+
970
+ def _translated_body(exc, payload: dict, target: Target, path: str) -> ApiError:
971
+ """`_translate`, for a caller that already consumed the error body.
972
+
973
+ ``HTTPError.read()`` can only be called once, so a POST-family
974
+ caller parses the body itself and hands it here rather than
975
+ letting `_translate` read an exhausted stream, which would
976
+ silently produce an empty payload and a message missing its
977
+ reason.
978
+ """
979
+ code = payload.get("error") if isinstance(payload, dict) else None
980
+ detail = payload.get("message") if isinstance(payload, dict) else None
981
+
982
+ if exc.code == 401 or code == "not-authenticated":
983
+ return NotAuthenticated(
984
+ f"401 from {target.name}: no valid session.\n"
985
+ f"Run `fm login --host {target.name}`"
986
+ )
987
+ if code == "cli-admin-scope-required":
988
+ return _cli_scope_refusal(target, detail)
989
+
990
+ if exc.code == 403 or code == "platform-admin-required":
991
+ # Sibling: `_translated`'s 403 branch answers for the same gate,
992
+ # and the 404 branch below already carries the same warning as
993
+ # its sibling for the same reason. If you change either 403
994
+ # message, change the other.
995
+ return ApiError(
996
+ f"403 from {target.name} on {path}: this needs User.is_platform_admin "
997
+ "on your user row.\n"
998
+ "The gate is site-wide platform admin, re-checked on every call. It "
999
+ "never consults the project, so being owner or admin of this space, "
1000
+ "or a member of it at all, is neither necessary nor sufficient.\n"
1001
+ "Run `fm spaces`, which reads /admin/spaces behind the identical "
1002
+ "flag, so a working `fm spaces` is what proves you have it. "
1003
+ "`fm whoami` cannot: it decodes the stored token locally and never "
1004
+ "asks the server.\n"
1005
+ "Do not retry THIS command with `--host evane`. That flag is correct "
1006
+ "for `fm spaces` (/admin is served from Global only) and wrong here: this "
1007
+ "endpoint is region-scoped, and a bulk write aimed at the wrong region is "
1008
+ "the one thing it exists to refuse (421, naming where to retry).\n"
1009
+ "The flag is granted by another platform admin via "
1010
+ "PATCH /admin/users/{id}."
1011
+ )
1012
+ if exc.code == 404:
1013
+ # Same wording and same reason as the GET path above: this branch
1014
+ # is `_translated`'s sibling for the exact same ambiguity, and
1015
+ # must change with it.
1016
+ if code:
1017
+ return ApiError(f"404 from {target.name} on {path}: {detail or code}")
1018
+ return ApiError(
1019
+ f"404 from {target.name}: {path} is not served there.\n"
1020
+ "Two different things look identical here and fm cannot tell them "
1021
+ "apart: the path may be wrong, or it may be right and simply not in "
1022
+ "the image this region is running.\n"
1023
+ f"Run `fm instance --host {target.name}` to report the deployed build "
1024
+ "and migration revision. Compare it with the code you are holding; "
1025
+ "that measures the answer, where fm could only guess it."
1026
+ )
1027
+ return ApiError(f"{exc.code} from {target.name} on {path}: {detail or code or exc.reason}")