| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166 |
- """Remote write computation (contract.md §6.4, §15.2).
- Pure functions over JSON-shaped documents; no I/O. The plane runs the authoritative write check;
- the agent runs the same check before sending so a locked write fails with a clear message and
- nothing goes on the wire.
- """
- from __future__ import annotations
- import copy
- from typing import Any, Dict, Iterator, List, Optional, Sequence, Tuple
- from .paths import Path, covers, encode
- Locks = Sequence[tuple[Path, str]]
- def json_equal(a: Any, b: Any) -> bool:
- """Structural JSON equality: numbers by value, but ``True`` is not ``1``."""
- if isinstance(a, bool) or isinstance(b, bool):
- return type(a) is type(b) and a == b
- if isinstance(a, int | float) and isinstance(b, int | float):
- return a == b
- if isinstance(a, dict) and isinstance(b, dict):
- return a.keys() == b.keys() and all(json_equal(a[k], b[k]) for k in a)
- if isinstance(a, list) and isinstance(b, list):
- return len(a) == len(b) and all(json_equal(x, y) for x, y in zip(a, b))
- return type(a) is type(b) and a == b
- def diff(base: dict[str, Any], new: dict[str, Any], prefix: Path = ()) -> tuple[dict[Path, Any], list[Path]]:
- """``(set, unset)`` turning ``base`` into ``new`` (§15.2 step 5). A changed list is one
- whole-list ``set`` (D8); a key equal to its base value is not sent."""
- sets: dict[Path, Any] = {}
- unsets: list[Path] = []
- for key, value in new.items():
- p = prefix + (key,)
- if key not in base:
- sets[p] = value
- elif isinstance(base[key], dict) and isinstance(value, dict):
- s, u = diff(base[key], value, p)
- sets.update(s)
- unsets.extend(u)
- elif not json_equal(base[key], value):
- sets[p] = value
- unsets.extend(prefix + (key,) for key in base if key not in new)
- return sets, unsets
- def intent_diff(base: dict[str, Any], new: dict[str, Any], prefix: Path = ()) -> tuple[dict[Path, Any], list[Path]]:
- """:func:`diff` as a caller's *intent*: the key-level edit a write means, to be re-applied to a
- newer document after a CAS conflict (§15.3). A mapping the base did not hold as a mapping
- (absent, or a scalar) is expanded to its leaves: writing ``terminal.timeout`` into a profile
- with no ``terminal`` section means "set that key", not "replace whatever ``terminal`` holds by
- the time the retry runs" — another writer's ``terminal.persistent`` must survive it. Only an
- empty mapping stays a whole value (there is no leaf to name); :func:`apply_intent` adds it
- without replacing a mapping that appeared meanwhile."""
- sets: dict[Path, Any] = {}
- unsets: list[Path] = []
- for key, value in new.items():
- p = prefix + (key,)
- old = base.get(key, _ABSENT)
- if isinstance(value, dict) and value and not isinstance(old, dict):
- s, _ = intent_diff({}, value, p)
- sets.update(s)
- elif key not in base:
- sets[p] = value
- elif isinstance(old, dict) and isinstance(value, dict):
- s, u = intent_diff(old, value, p)
- sets.update(s)
- unsets.extend(u)
- elif not json_equal(old, value):
- sets[p] = value
- unsets.extend(prefix + (key,) for key in base if key not in new)
- return sets, unsets
- _ABSENT = object()
- def apply_intent(doc: dict[str, Any], sets: dict[Path, Any], unsets: Sequence[Path]) -> None:
- """Apply an :func:`intent_diff` edit to *doc* in place."""
- for p, v in sets.items():
- if isinstance(v, dict) and not v:
- found, cur = _get_path(doc, p)
- if found and isinstance(cur, dict):
- continue # "make this a mapping": a mapping is already there, with its keys
- _set_path(doc, p, copy.deepcopy(v))
- for p in unsets:
- _pop_path(doc, p)
- def _set_path(doc: dict[str, Any], path: Path, value: Any) -> None:
- node = doc
- for seg in path[:-1]:
- if not isinstance(node.get(seg), dict):
- node[seg] = {}
- node = node[seg]
- node[path[-1]] = value
- def _pop_path(doc: dict[str, Any], path: Path) -> bool:
- node: Any = doc
- for seg in path[:-1]:
- if not isinstance(node, dict) or not isinstance(node.get(seg), dict):
- return False
- node = node[seg]
- if isinstance(node, dict) and path[-1] in node:
- del node[path[-1]]
- return True
- return False
- def _get_path(doc: dict[str, Any], path: Path) -> tuple[bool, Any]:
- node: Any = doc
- for seg in path:
- if not isinstance(node, dict) or seg not in node:
- return False, None
- node = node[seg]
- return True, node
- def strip_locked(base: dict[str, Any], new: dict[str, Any], locks: Locks) -> tuple[dict[str, Any], dict[str, Any], list[Path]]:
- """Drop every locked path from BOTH documents (§15.2 step 1), so a bulk write neither sets
- nor unsets a key it may not touch. Returns the copies and the locked paths whose new value
- differed from the effective one (the ones the caller tried to change)."""
- base, new = copy.deepcopy(base), copy.deepcopy(new)
- changed: list[Path] = []
- for lock, _level in locks:
- in_base, base_val = _get_path(base, lock)
- in_new, new_val = _get_path(new, lock)
- if in_base != in_new or (in_new and not json_equal(base_val, new_val)):
- changed.append(lock)
- _pop_path(base, lock)
- _pop_path(new, lock)
- return base, new, changed
- def _touched(path: Path, value: Any) -> Iterator[tuple[Path, Any]]:
- """``(touched path, value written there)`` for ``set path = value`` (§6.4 rule 2): the path
- itself and every path inside ``value``, descending through objects only."""
- yield path, value
- if isinstance(value, dict):
- for k, v in value.items():
- yield from _touched(path + (k,), v)
- def write_check(sets: dict[Path, Any], unsets: Sequence[Path], locks: Locks) -> Optional[tuple[Path, str]]:
- """The ``(lock path, level)`` that refuses this write (§6.4 rules 1-3), or None."""
- for p in unsets:
- for lock, level in locks:
- if covers(lock, p):
- return lock, level
- for p, v in sets.items():
- for t, tv in _touched(p, v):
- for lock, level in locks:
- if covers(lock, t):
- return lock, level
- # R7: a non-object written at a strict ancestor of a lock would replace the
- # locked subtree through deep merge.
- if len(t) < len(lock) and covers(t, lock) and not isinstance(tv, dict):
- return lock, level
- return None
- def encode_changes(sets: dict[Path, Any], unsets: Sequence[Path]) -> tuple[dict[str, Any], list[str]]:
- return {encode(p): v for p, v in sets.items()}, [encode(p) for p in unsets]
|