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/update.py ADDED
@@ -0,0 +1,433 @@
1
+ """``fm update`` - a bulk data change an operator can make without writing code.
2
+
3
+ The wire format is the server's, not this module's: ``POST
4
+ /projects/{project_id}/admin/data-changes`` defines ``$action``, ``$kind``,
5
+ ``$id``, ``$set``, ``$expect``, ``$ref``, ``$replace_data``, ``$hard``,
6
+ ``apply`` defaulting to false, and a 500-op bound. This module does not
7
+ invent a second format and does not reinterpret that one. It adds exactly
8
+ one thing, on the operator's side of the wire: ``$name``, resolved to an
9
+ ``$id`` here, in the client, seconds before the write, against the
10
+ environment being written. The server never sees a ``$name``.
11
+
12
+ Why ``$name`` has to exist: the endpoint's ``$ref`` looks like it covers
13
+ this and does not. It is a strictly backward, within-batch reference to a
14
+ row the same request just created, so an ``update`` or a ``delete`` has no
15
+ way to name an existing row except by literal UUID, and a wrong one lands
16
+ in a jsonb column with no foreign key and nothing errors. Every
17
+ organisation's id differs between environments, which is exactly the kind
18
+ of id an operator should never type or copy by hand.
19
+
20
+ The copy-back is the point, not the convenience. Resolving a name
21
+ client-side would, on its own, just move the guess. So the name the
22
+ client resolved by is written back into ``$expect``, carrying the raw
23
+ column value the server returned. The server then re-checks it exactly,
24
+ without coalescing shapes. A mis-resolution is therefore refused by the
25
+ row itself rather than written to confidently: the client's answer is
26
+ verified by the thing it is about to change, structurally, rather than by
27
+ anyone remembering to check.
28
+
29
+ A foreign reference inside ``$set`` (``parent_id`` and friends) cannot be
30
+ guarded that way: it points at a different row, and ``$expect`` only
31
+ describes the row being changed. There, the guard is the plan report:
32
+ every resolution is recorded and printed, and the server's own
33
+ unresolved-reference check refuses a reference that is not a real row in
34
+ the project. Between them, a wrong foreign id is visible before the write
35
+ and refused during it.
36
+
37
+ A partial ``data`` merges, not replaces. STAKEHOLDER and CUSTOM rows carry
38
+ a free-form ``data`` JSONB blob. ``$set`` naming ``data`` merges into
39
+ whatever the row already holds, so ``{"data": {"country": "AE"}}``
40
+ changes only ``country``, and every other key on the row survives. This
41
+ is the server's default, not something this module does; it matters here
42
+ because ``$expect`` still makes you name the row's current full ``data``
43
+ value, which is a different thing from the partial value you are
44
+ writing. Pass ``"$replace_data": true`` in an op to replace the whole
45
+ blob instead, the only way to remove a key, since a merge keeps every key
46
+ the payload does not mention.
47
+
48
+ A delete is soft, not permanent. ``$action: "delete"`` stamps
49
+ ``deleted_at`` and lands the row in the space's trash, restorable,
50
+ exactly like the UI's trash icon. ``$hard`` is refused for a kind that has
51
+ a trash entry (purge one from there instead) and required for the two
52
+ that do not (FILE_LINK, SESSION_PARTICIPANT), whose delete has always
53
+ been permanent.
54
+
55
+ Stdlib only.
56
+ """
57
+
58
+ from __future__ import annotations
59
+
60
+ import hashlib
61
+ import json
62
+ from collections.abc import Callable
63
+ from dataclasses import dataclass, field
64
+ from typing import Any
65
+
66
+ from formist_cli.resolve import ResolutionError, resolve_one
67
+ from formist_cli.targets import Target
68
+
69
+ #: Mirrors the server's own op-count bound. Duplicated deliberately rather
70
+ #: than imported: `fm` is stdlib-only and must run without the server's
71
+ #: dependency tree. Refusing here means the operator reads a sentence
72
+ #: about the bound instead of a validation error from the server.
73
+ MAX_OPS = 500
74
+
75
+ #: The endpoint's own vocabulary. Listed so a typo in a payload is a legible
76
+ #: refusal rather than an ``extra: forbid`` validation error from the server.
77
+ #: ``$replace_data`` opts an op back into wholesale-replacing ``$set.data``
78
+ #: instead of the server's default merge, and ``$hard`` names an explicit
79
+ #: hard/soft delete choice.
80
+ _OP_KEYS = {
81
+ "$action", "$kind", "$id", "$set", "$expect", "$ref",
82
+ "$replace_data", "$hard",
83
+ }
84
+ _ACTIONS = {"add", "update", "delete"}
85
+
86
+
87
+ class UpdateError(Exception):
88
+ """A payload that will not be sent. Written for an operator."""
89
+
90
+
91
+ @dataclass(frozen=True)
92
+ class Resolution:
93
+ """One ``$name`` that became an id, and where it was."""
94
+
95
+ where: str
96
+ kind: str
97
+ name: str
98
+ id: str
99
+ #: The raw column value the match was made on, what goes into ``$expect``.
100
+ value: Any = None
101
+ field_name: str | None = None
102
+
103
+ def describe(self) -> str:
104
+ return f"{self.where}: {self.kind} {self.name!r} -> {self.id}"
105
+
106
+
107
+ @dataclass(frozen=True)
108
+ class Plan:
109
+ """A resolved, ready-to-send request plus what had to be looked up to build it."""
110
+
111
+ env: str
112
+ space: str
113
+ ops: list[dict]
114
+ resolutions: list[Resolution] = field(default_factory=list)
115
+
116
+ @property
117
+ def body(self) -> dict:
118
+ """The request body. ``apply`` is always False here, see :func:`send`."""
119
+ return {"apply": False, "ops": self.ops}
120
+
121
+
122
+ def load_payload(path: str) -> Any:
123
+ try:
124
+ with open(path, encoding="utf-8") as handle:
125
+ return json.load(handle)
126
+ except FileNotFoundError:
127
+ raise UpdateError(f"no such payload file: {path}") from None
128
+ except json.JSONDecodeError as exc:
129
+ raise UpdateError(f"{path} is not valid JSON: {exc}") from None
130
+ except OSError as exc:
131
+ raise UpdateError(f"could not read {path}: {exc}") from None
132
+
133
+
134
+ def _is_name_ref(value: Any) -> bool:
135
+ return isinstance(value, dict) and "$name" in value
136
+
137
+
138
+ def _resolve_name(
139
+ name: str,
140
+ kind: str,
141
+ where: str,
142
+ *,
143
+ target: Target,
144
+ space: str,
145
+ token: str | None,
146
+ fetch: Callable | None,
147
+ ):
148
+ try:
149
+ return resolve_one(
150
+ name, kind=kind, target=target, space=space, token=token, fetch=fetch
151
+ )
152
+ except ResolutionError as exc:
153
+ # The op index is the thing the operator needs; the endpoint reports
154
+ # refusals by index too, so the two vocabularies match.
155
+ raise UpdateError(f"{where}: {exc}") from None
156
+
157
+
158
+ def build_plan(
159
+ payload: Any,
160
+ *,
161
+ target: Target,
162
+ space: str,
163
+ token: str | None = None,
164
+ fetch: Callable | None = None,
165
+ ) -> Plan:
166
+ """Validate a payload and resolve every ``$name`` in it, or refuse entirely.
167
+
168
+ All-or-nothing, matching the endpoint: a partially resolved batch is a plan
169
+ nobody reviewed.
170
+ """
171
+ if not isinstance(payload, dict):
172
+ raise UpdateError(
173
+ "a payload must be a JSON object like "
174
+ '{"ops": [...]}, got a ' + type(payload).__name__ + "."
175
+ )
176
+ ops = payload.get("ops")
177
+ if not isinstance(ops, list):
178
+ raise UpdateError('a payload must carry an "ops" list.')
179
+ if not ops:
180
+ raise UpdateError("no ops in this payload, nothing to do.")
181
+ if len(ops) > MAX_OPS:
182
+ raise UpdateError(
183
+ f"{len(ops)} ops, over the {MAX_OPS}-op bound the endpoint enforces. "
184
+ "The bound caps transaction duration; split the change into batches."
185
+ )
186
+
187
+ resolved_ops: list[dict] = []
188
+ resolutions: list[Resolution] = []
189
+
190
+ for index, op in enumerate(ops):
191
+ where = f"op {index}"
192
+ if not isinstance(op, dict):
193
+ raise UpdateError(f"{where}: an op must be a JSON object.")
194
+
195
+ action = op.get("$action")
196
+ if action not in _ACTIONS:
197
+ raise UpdateError(
198
+ f"{where}: $action must be one of {', '.join(sorted(_ACTIONS))}; "
199
+ f"got {action!r}."
200
+ )
201
+ kind = op.get("$kind")
202
+ if not isinstance(kind, str):
203
+ raise UpdateError(f"{where}: $kind is required and must be a string.")
204
+
205
+ unknown = set(op) - _OP_KEYS - {"$name"}
206
+ if unknown:
207
+ raise UpdateError(
208
+ f"{where}: unknown key(s) {', '.join(sorted(unknown))}. The endpoint "
209
+ f"forbids extras; valid keys are {', '.join(sorted(_OP_KEYS))} "
210
+ "(plus fm's own $name)."
211
+ )
212
+
213
+ new_op = {k: v for k, v in op.items() if k != "$name"}
214
+
215
+ # --- $name in the $id position -------------------------------------
216
+ if "$name" in op:
217
+ if "$id" in op:
218
+ raise UpdateError(
219
+ f"{where}: carries both $id and $name. They are two answers to "
220
+ "the same question; keep the one you trust."
221
+ )
222
+ match = _resolve_name(
223
+ str(op["$name"]), kind, where,
224
+ target=target, space=space, token=token, fetch=fetch,
225
+ )
226
+ new_op["$id"] = match.id
227
+
228
+ # The copy-back. This is what makes the resolution self-checking.
229
+ expect = dict(new_op.get("$expect") or {})
230
+ if match.field in expect and expect[match.field] != match.value:
231
+ raise UpdateError(
232
+ f"{where}: $expect says {match.field} is "
233
+ f"{expect[match.field]!r}, but the row resolved by name "
234
+ f"{op['$name']!r} holds {match.value!r}.\n"
235
+ "Refusing rather than replacing your expectation: you and the "
236
+ "server disagree about this row, and that disagreement is the "
237
+ "finding, not an inconvenience."
238
+ )
239
+ expect[match.field] = match.value
240
+ new_op["$expect"] = expect
241
+
242
+ resolutions.append(
243
+ Resolution(
244
+ where=where, kind=kind, name=str(op["$name"]), id=match.id,
245
+ value=match.value, field_name=match.field,
246
+ )
247
+ )
248
+
249
+ # --- $name inside $set (a foreign reference) ------------------------
250
+ set_ = new_op.get("$set")
251
+ if isinstance(set_, dict):
252
+ new_set = {}
253
+ for column, value in set_.items():
254
+ if _is_name_ref(value):
255
+ ref_kind = value.get("$kind") or kind
256
+ ref_name = str(value["$name"])
257
+ ref_where = f"{where} $set.{column}"
258
+ match = _resolve_name(
259
+ ref_name, str(ref_kind), ref_where,
260
+ target=target, space=space, token=token, fetch=fetch,
261
+ )
262
+ new_set[column] = match.id
263
+ resolutions.append(
264
+ Resolution(
265
+ where=ref_where, kind=str(ref_kind), name=ref_name,
266
+ id=match.id, value=match.value, field_name=match.field,
267
+ )
268
+ )
269
+ else:
270
+ # `$ref` is the endpoint's within-batch back-reference and is
271
+ # left exactly as written. Resolving it here would be a second
272
+ # implementation of someone else's contract.
273
+ new_set[column] = value
274
+ new_op["$set"] = new_set
275
+
276
+ resolved_ops.append(new_op)
277
+
278
+ return Plan(
279
+ env=target.env, space=space, ops=resolved_ops, resolutions=resolutions
280
+ )
281
+
282
+
283
+ def _canonical(value: Any) -> str:
284
+ return json.dumps(value, sort_keys=True, ensure_ascii=False, default=str)
285
+
286
+
287
+ def plan_token(plan: Plan, dry_run_report: Any) -> str:
288
+ """A short token proving the operator saw this dry run for this target.
289
+
290
+ Hashed over the environment, the space, the resolved ops, and the dry run's own
291
+ result. Each is load-bearing:
292
+
293
+ - env and space, so a plan is not portable. A token minted against local
294
+ cannot apply against ``ae``.
295
+ - resolved ops, so a re-resolution that landed on a different row (someone
296
+ renamed something in between) invalidates it.
297
+ - the dry-run report, so a plan whose meaning changed server-side is
298
+ refused even when the ops are byte-identical: the dry run executes for real
299
+ and rolls back, so its report reflects live state.
300
+
301
+ This is deliberately not a y/n confirmation: there is nothing for ``yes |`` to
302
+ answer, and a script can carry the token, so automation stays possible while
303
+ staying explicit. It is also not a retyped id prefix: eight characters are not
304
+ a reliable discriminator across a real dataset.
305
+ """
306
+ digest = hashlib.sha256(
307
+ _canonical(
308
+ {
309
+ "env": plan.env,
310
+ "space": plan.space,
311
+ "ops": plan.ops,
312
+ "report": _stable_report(plan, dry_run_report),
313
+ }
314
+ ).encode()
315
+ ).hexdigest()
316
+ return digest[:12]
317
+
318
+
319
+ def _stable_report(plan: Plan, report: Any) -> Any:
320
+ """What the dry run meant, with what it happened to name stripped out.
321
+
322
+ A dry run executes every op for real and rolls back, so the server
323
+ mints a fresh ``audit_id`` on every call and a fresh row ``id`` for
324
+ every ``add``. Hashing the report verbatim would therefore produce a
325
+ different token on each run of an unchanged plan, making
326
+ ``--apply <token>`` impossible to satisfy.
327
+
328
+ So the projection keeps ``counts``, each result's
329
+ ``index``/``action``/``kind``/``outcome``/``cascaded``, and every
330
+ refusal's ``index``/``reason``, all of which change when the plan's
331
+ meaning changes. A result's ``id`` is kept only where the plan already
332
+ determined it (the op carried an ``$id``); on an ``add`` the id is
333
+ minted by the insert and is per-run noise, exactly like ``audit_id``.
334
+ """
335
+ if not isinstance(report, dict):
336
+ return report
337
+
338
+ plan_ids = [op.get("$id") for op in plan.ops]
339
+
340
+ results = []
341
+ for result in report.get("results") or []:
342
+ if not isinstance(result, dict):
343
+ continue
344
+ index = result.get("index")
345
+ kept = {
346
+ "index": index,
347
+ "action": result.get("action"),
348
+ "kind": result.get("kind"),
349
+ "outcome": result.get("outcome"),
350
+ "cascaded": result.get("cascaded"),
351
+ "changed": result.get("changed"),
352
+ }
353
+ # Plan-determined ids pin the row; server-generated ones are noise.
354
+ if isinstance(index, int) and 0 <= index < len(plan_ids) and plan_ids[index]:
355
+ kept["id"] = result.get("id")
356
+ results.append(kept)
357
+
358
+ refusals = [
359
+ {"index": r.get("index"), "reason": r.get("reason")}
360
+ for r in (report.get("refusals") or [])
361
+ if isinstance(r, dict)
362
+ ]
363
+
364
+ return {
365
+ "counts": report.get("counts"),
366
+ "committed": report.get("committed"),
367
+ "results": results,
368
+ "refusals": refusals,
369
+ }
370
+
371
+
372
+ ENDPOINT = "/projects/{space}/admin/data-changes"
373
+
374
+ #: Said in `--help` and in the 404 so a missing endpoint fails legibly
375
+ #: rather than as a mystery. Deliberately names no branch, PR or
376
+ #: deployment state, since none of those are facts a client can hold; it
377
+ #: describes what a 404 means and names the command that measures the
378
+ #: answer.
379
+ NOT_DEPLOYED_NOTE = (
380
+ "NOTE: if a region answers 404 here, the bulk endpoint is not in the image that "
381
+ "region is running, and `fm update` can only work against a server that serves "
382
+ "it. `fm instance --host <host>` reports what is actually deployed there; fm "
383
+ "cannot tell a missing route from a wrong one from the client side."
384
+ )
385
+
386
+
387
+ def dry_run(plan: Plan, target: Target, *, token: str | None, post=None) -> Any:
388
+ """Execute the plan with ``apply:false``.
389
+
390
+ The endpoint runs every op for real and rolls the transaction back,
391
+ so this reports the ids the inserts actually produced rather than ids
392
+ it predicted.
393
+ """
394
+ from formist_cli import api
395
+
396
+ post = post or api.post
397
+ return post(target, ENDPOINT.format(space=plan.space), plan.body, token=token)
398
+
399
+
400
+ def apply(
401
+ plan: Plan,
402
+ target: Target,
403
+ *,
404
+ token: str | None,
405
+ supplied_token: str,
406
+ post=None,
407
+ ) -> Any:
408
+ """Re-run the dry run, check the operator's plan token, then commit.
409
+
410
+ The dry run is repeated inside this call rather than trusted from a previous
411
+ one, because a token proves the operator saw a plan, not that the plan is still
412
+ true. Re-running is what makes the token a check instead of a receipt.
413
+ """
414
+ from formist_cli import api
415
+
416
+ post = post or api.post
417
+ report = dry_run(plan, target, token=token, post=post)
418
+ current = plan_token(plan, report)
419
+ if current != supplied_token:
420
+ raise UpdateError(
421
+ "REFUSING TO APPLY: this plan no longer matches the one you were shown.\n"
422
+ f" you supplied: {supplied_token}\n"
423
+ f" current plan: {current}\n"
424
+ "\n"
425
+ "Nothing was applied. The token covers the environment, the space, the "
426
+ "resolved ops and the dry run's own result, so one of those changed: a "
427
+ "row moved under the plan, a name now resolves elsewhere, or this is a "
428
+ "plan for a different target.\n"
429
+ "\n"
430
+ "-> Re-run the dry run, read it, and apply with the token it prints."
431
+ )
432
+ body = {"apply": True, "ops": plan.ops}
433
+ return post(target, ENDPOINT.format(space=plan.space), body, token=token)