| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132 |
- """Client-side value rules of the config plane wire contract.
- - :func:`to_wire` — YAML-derived Python values → JSON values (contract.md §4.1, §4.2). Runs on the
- whole new user-layer document BEFORE the diff, so a conversion never shows up as a change (§4.3).
- - :func:`secret_literal_path` — the secret-shaped-key rule (§14, D17), driven by the vendored
- ``config-secret-keys.json`` fixture so the agent and the plane use one list. The plane re-checks
- every write; this check exists so a literal is never sent.
- """
- from __future__ import annotations
- import datetime
- import json
- import logging
- import math
- import re
- from functools import lru_cache
- from pathlib import Path as _FsPath
- from typing import Any, Dict, Iterator, Optional, Sequence, Tuple
- from hermes_cli.config_backend import ConfigValueError
- from .paths import Path, encode
- logger = logging.getLogger(__name__)
- MAX_SAFE_INTEGER = 2**53 - 1
- VENDOR_DIR = _FsPath(__file__).resolve().parent / "vendor"
- SECRET_KEYS_FIXTURE = VENDOR_DIR / "conformance" / "config-secret-keys.json"
- def to_wire(value: Any, path: Path = ()) -> Any:
- """``value`` converted per §4.1/§4.2; raises :class:`ConfigValueError` naming the path."""
- if value is None or isinstance(value, (str, bool)):
- return value
- if isinstance(value, int):
- if -MAX_SAFE_INTEGER <= value <= MAX_SAFE_INTEGER:
- return value
- logger.warning("config path %s: integer %d is outside ±(2^53-1); sent as a decimal string",
- encode(path) or "<root>", value)
- return str(value)
- if isinstance(value, float):
- if math.isnan(value) or math.isinf(value):
- raise ConfigValueError(f"{encode(path) or '<root>'}: NaN/Infinity cannot be stored in Remote Config")
- return value
- if isinstance(value, datetime.datetime | datetime.date):
- return value.isoformat()
- if isinstance(value, list | tuple):
- return [to_wire(v, path) for v in value]
- if isinstance(value, dict):
- out: dict[str, Any] = {}
- for k, v in value.items():
- key = _wire_key(k, path)
- if key in out:
- raise ConfigValueError(
- f"{encode(path + (key,))}: two keys become the same string key {key!r}")
- out[key] = to_wire(v, path + (key,))
- return out
- raise ConfigValueError(
- f"{encode(path) or '<root>'}: a {type(value).__name__} value cannot be stored in Remote Config")
- def _wire_key(key: Any, path: Path) -> str:
- if isinstance(key, str):
- return key
- if isinstance(key, int) and not isinstance(key, bool):
- return str(key)
- raise ConfigValueError(
- f"{encode(path) or '<root>'}: a {type(key).__name__} mapping key ({key!r}) cannot be stored "
- "in Remote Config; quote it in YAML")
- # --- secret-shaped keys (§14) -----------------------------------------------------------------
- @lru_cache(maxsize=1)
- def _secret_rules() -> dict[str, Any]:
- data = json.loads(SECRET_KEYS_FIXTURE.read_text(encoding="utf-8-sig"))
- return {
- "secret_keys": frozenset(data["secretKeys"]),
- "secret_suffixes": tuple(data["secretKeySuffixes"]),
- "non_secret_suffixes": tuple(data["nonSecretKeySuffixes"]),
- "env_keys": frozenset(data["envConfigKeys"]),
- "env_suffixes": tuple(data["envConfigKeySuffixes"]),
- "env_prefixes": tuple(data["envConfigKeyPrefixes"]),
- # fullmatch: Python's ``$`` also matches before a trailing newline, so ``re.match`` with the
- # fixture pattern would accept ``"${X}\n"`` (a fixture vector the plane rejects).
- "placeholder": re.compile(data["placeholderPattern"]),
- "non_secret_paths": frozenset(tuple(p) for p in data["nonSecretPaths"]),
- }
- def _is_env_config_key(key: str, rules: dict[str, Any]) -> bool:
- if "." in key:
- return False
- up = key.upper()
- return up in rules["env_keys"] or up.endswith(rules["env_suffixes"]) or up.startswith(rules["env_prefixes"])
- def is_secret_path(segments: Sequence[str]) -> bool:
- """§14.2 on decoded segments (list indices already dropped)."""
- rules = _secret_rules()
- if tuple(segments) in rules["non_secret_paths"]:
- return False
- last = segments[-1]
- leaf = last.lower().replace("-", "_")
- if len(segments) == 1 and _is_env_config_key(last, rules):
- return not leaf.endswith(rules["non_secret_suffixes"])
- return leaf in rules["secret_keys"] or leaf.endswith(rules["secret_suffixes"])
- def _walk(value: Any, path: Path) -> Iterator[tuple[Path, Any]]:
- yield path, value
- if isinstance(value, dict):
- for k, v in value.items():
- yield from _walk(v, path + (str(k),))
- elif isinstance(value, list):
- for v in value: # list elements inherit the list's path (§14.3)
- yield from _walk(v, path)
- def secret_literal_path(path: Path, value: Any) -> Optional[Path]:
- """The first path under ``set path = value`` that holds a secret literal (§14.3), or None."""
- placeholder = _secret_rules()["placeholder"]
- for node_path, node in _walk(value, path):
- if not node_path or not is_secret_path(node_path):
- continue
- if isinstance(node, bool) or node is None:
- continue
- if isinstance(node, str) and (node == "" or placeholder.fullmatch(node)):
- continue
- if isinstance(node, str | int | float):
- return node_path
- return None
|