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/__init__.py +1 -0
- formist_cli/__main__.py +3 -0
- formist_cli/airtable.py +238 -0
- formist_cli/alerts.py +207 -0
- formist_cli/api.py +1027 -0
- formist_cli/chat.py +618 -0
- formist_cli/chats.py +517 -0
- formist_cli/cli.py +1367 -0
- formist_cli/cli_support.py +221 -0
- formist_cli/connectors.py +358 -0
- formist_cli/context.py +164 -0
- formist_cli/diff.py +943 -0
- formist_cli/doctor.py +128 -0
- formist_cli/export.py +427 -0
- formist_cli/files.py +670 -0
- formist_cli/importer.py +425 -0
- formist_cli/kb.py +185 -0
- formist_cli/login.py +615 -0
- formist_cli/logs.py +781 -0
- formist_cli/meetings.py +200 -0
- formist_cli/messages.py +414 -0
- formist_cli/participants.py +402 -0
- formist_cli/prefs.py +328 -0
- formist_cli/privileges.py +375 -0
- formist_cli/projects.py +127 -0
- formist_cli/resolve.py +443 -0
- formist_cli/settings.py +199 -0
- formist_cli/skill_library.py +246 -0
- formist_cli/skills.py +308 -0
- formist_cli/space_plan.py +411 -0
- formist_cli/spaces.py +693 -0
- formist_cli/targets.py +153 -0
- formist_cli/textnorm.py +26 -0
- formist_cli/tokens.py +339 -0
- formist_cli/update.py +433 -0
- formist_cli/uploads.py +928 -0
- formist_cli/usage_tokens.py +152 -0
- formist_cli/users.py +384 -0
- formist_cli/whatsapp.py +451 -0
- formist_cli-0.1.0.dist-info/METADATA +176 -0
- formist_cli-0.1.0.dist-info/RECORD +44 -0
- formist_cli-0.1.0.dist-info/WHEEL +4 -0
- formist_cli-0.1.0.dist-info/entry_points.txt +2 -0
- formist_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
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}")
|