values.py 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. """Client-side value rules of the config plane wire contract.
  2. - :func:`to_wire` — YAML-derived Python values → JSON values (contract.md §4.1, §4.2). Runs on the
  3. whole new user-layer document BEFORE the diff, so a conversion never shows up as a change (§4.3).
  4. - :func:`secret_literal_path` — the secret-shaped-key rule (§14, D17), driven by the vendored
  5. ``config-secret-keys.json`` fixture so the agent and the plane use one list. The plane re-checks
  6. every write; this check exists so a literal is never sent.
  7. """
  8. from __future__ import annotations
  9. import datetime
  10. import json
  11. import logging
  12. import math
  13. import re
  14. from functools import lru_cache
  15. from pathlib import Path as _FsPath
  16. from typing import Any, Dict, Iterator, Optional, Sequence, Tuple
  17. from hermes_cli.config_backend import ConfigValueError
  18. from .paths import Path, encode
  19. logger = logging.getLogger(__name__)
  20. MAX_SAFE_INTEGER = 2**53 - 1
  21. VENDOR_DIR = _FsPath(__file__).resolve().parent / "vendor"
  22. SECRET_KEYS_FIXTURE = VENDOR_DIR / "conformance" / "config-secret-keys.json"
  23. def to_wire(value: Any, path: Path = ()) -> Any:
  24. """``value`` converted per §4.1/§4.2; raises :class:`ConfigValueError` naming the path."""
  25. if value is None or isinstance(value, (str, bool)):
  26. return value
  27. if isinstance(value, int):
  28. if -MAX_SAFE_INTEGER <= value <= MAX_SAFE_INTEGER:
  29. return value
  30. logger.warning("config path %s: integer %d is outside ±(2^53-1); sent as a decimal string",
  31. encode(path) or "<root>", value)
  32. return str(value)
  33. if isinstance(value, float):
  34. if math.isnan(value) or math.isinf(value):
  35. raise ConfigValueError(f"{encode(path) or '<root>'}: NaN/Infinity cannot be stored in Remote Config")
  36. return value
  37. if isinstance(value, datetime.datetime | datetime.date):
  38. return value.isoformat()
  39. if isinstance(value, list | tuple):
  40. return [to_wire(v, path) for v in value]
  41. if isinstance(value, dict):
  42. out: dict[str, Any] = {}
  43. for k, v in value.items():
  44. key = _wire_key(k, path)
  45. if key in out:
  46. raise ConfigValueError(
  47. f"{encode(path + (key,))}: two keys become the same string key {key!r}")
  48. out[key] = to_wire(v, path + (key,))
  49. return out
  50. raise ConfigValueError(
  51. f"{encode(path) or '<root>'}: a {type(value).__name__} value cannot be stored in Remote Config")
  52. def _wire_key(key: Any, path: Path) -> str:
  53. if isinstance(key, str):
  54. return key
  55. if isinstance(key, int) and not isinstance(key, bool):
  56. return str(key)
  57. raise ConfigValueError(
  58. f"{encode(path) or '<root>'}: a {type(key).__name__} mapping key ({key!r}) cannot be stored "
  59. "in Remote Config; quote it in YAML")
  60. # --- secret-shaped keys (§14) -----------------------------------------------------------------
  61. @lru_cache(maxsize=1)
  62. def _secret_rules() -> dict[str, Any]:
  63. data = json.loads(SECRET_KEYS_FIXTURE.read_text(encoding="utf-8-sig"))
  64. return {
  65. "secret_keys": frozenset(data["secretKeys"]),
  66. "secret_suffixes": tuple(data["secretKeySuffixes"]),
  67. "non_secret_suffixes": tuple(data["nonSecretKeySuffixes"]),
  68. "env_keys": frozenset(data["envConfigKeys"]),
  69. "env_suffixes": tuple(data["envConfigKeySuffixes"]),
  70. "env_prefixes": tuple(data["envConfigKeyPrefixes"]),
  71. # fullmatch: Python's ``$`` also matches before a trailing newline, so ``re.match`` with the
  72. # fixture pattern would accept ``"${X}\n"`` (a fixture vector the plane rejects).
  73. "placeholder": re.compile(data["placeholderPattern"]),
  74. "non_secret_paths": frozenset(tuple(p) for p in data["nonSecretPaths"]),
  75. }
  76. def _is_env_config_key(key: str, rules: dict[str, Any]) -> bool:
  77. if "." in key:
  78. return False
  79. up = key.upper()
  80. return up in rules["env_keys"] or up.endswith(rules["env_suffixes"]) or up.startswith(rules["env_prefixes"])
  81. def is_secret_path(segments: Sequence[str]) -> bool:
  82. """§14.2 on decoded segments (list indices already dropped)."""
  83. rules = _secret_rules()
  84. if tuple(segments) in rules["non_secret_paths"]:
  85. return False
  86. last = segments[-1]
  87. leaf = last.lower().replace("-", "_")
  88. if len(segments) == 1 and _is_env_config_key(last, rules):
  89. return not leaf.endswith(rules["non_secret_suffixes"])
  90. return leaf in rules["secret_keys"] or leaf.endswith(rules["secret_suffixes"])
  91. def _walk(value: Any, path: Path) -> Iterator[tuple[Path, Any]]:
  92. yield path, value
  93. if isinstance(value, dict):
  94. for k, v in value.items():
  95. yield from _walk(v, path + (str(k),))
  96. elif isinstance(value, list):
  97. for v in value: # list elements inherit the list's path (§14.3)
  98. yield from _walk(v, path)
  99. def secret_literal_path(path: Path, value: Any) -> Optional[Path]:
  100. """The first path under ``set path = value`` that holds a secret literal (§14.3), or None."""
  101. placeholder = _secret_rules()["placeholder"]
  102. for node_path, node in _walk(value, path):
  103. if not node_path or not is_secret_path(node_path):
  104. continue
  105. if isinstance(node, bool) or node is None:
  106. continue
  107. if isinstance(node, str) and (node == "" or placeholder.fullmatch(node)):
  108. continue
  109. if isinstance(node, str | int | float):
  110. return node_path
  111. return None