shared_metrics_send_config.py 3.3 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889
  1. """Configuration for shared-metrics transmission."""
  2. from __future__ import annotations
  3. import logging
  4. from dataclasses import dataclass
  5. from urllib.parse import urlparse
  6. logger = logging.getLogger(__name__)
  7. #: Production ingest endpoint. Overridable through config only — deliberately NOT by an
  8. #: environment variable: AGENTS.md reserves HERMES_* for secrets, and an inherited variable
  9. #: could silently redirect consented metrics to any host with nothing visible in config.
  10. #: Tests and the staging E2E write this key into a throwaway profile instead.
  11. DEFAULT_ENDPOINT = "https://telemetry.nousresearch.com/v1/telemetry"
  12. _LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "[::1]"})
  13. # Module-level latch: the enabled/send mismatch is a static misconfiguration,
  14. # so it is reported once per process instead of on every hook fire.
  15. _warned_send_without_collection = False
  16. @dataclass(frozen=True)
  17. class SendConfig:
  18. """Resolved transmission settings."""
  19. #: Collection is on. Nothing is packaged or sent without it.
  20. enabled: bool
  21. #: Transmission is on AND permitted (that is, collection is also on).
  22. send: bool
  23. #: Where packages are POSTed.
  24. endpoint: str
  25. def _endpoint_is_safe(endpoint: str) -> bool:
  26. """Reject plaintext destinations unless they are loopback (so tests can use local HTTP)."""
  27. try:
  28. parsed = urlparse(endpoint)
  29. except ValueError:
  30. return False
  31. if parsed.scheme == "https":
  32. return True
  33. return parsed.scheme == "http" and (parsed.hostname or "") in _LOCAL_HOSTS
  34. def resolve_send_config(config: dict | None) -> SendConfig:
  35. """Resolve transmission settings from config (endpoint: config > production default).
  36. ``send`` is False whenever transmission cannot legitimately happen, so callers never
  37. have to re-check the combination.
  38. """
  39. global _warned_send_without_collection
  40. raw = config if isinstance(config, dict) else {}
  41. telemetry = raw.get("telemetry")
  42. telemetry = telemetry if isinstance(telemetry, dict) else {}
  43. shared = telemetry.get("shared_metrics")
  44. shared = shared if isinstance(shared, dict) else {}
  45. enabled = shared.get("enabled") is True
  46. send_requested = shared.get("send") is True
  47. if send_requested and not enabled:
  48. # Loud, not silent: the user believes telemetry is being sent, and it never will be.
  49. if not _warned_send_without_collection:
  50. _warned_send_without_collection = True
  51. logger.error(
  52. "telemetry.shared_metrics.send is true but "
  53. "telemetry.shared_metrics.enabled is false — nothing is "
  54. "collected, so nothing can be sent. Enable collection or "
  55. "turn sending off."
  56. )
  57. return SendConfig(enabled=False, send=False, endpoint=DEFAULT_ENDPOINT)
  58. endpoint = shared.get("endpoint")
  59. if not isinstance(endpoint, str) or not endpoint.strip():
  60. endpoint = DEFAULT_ENDPOINT
  61. endpoint = endpoint.strip()
  62. if send_requested and not _endpoint_is_safe(endpoint):
  63. logger.error(
  64. "Refusing to send shared metrics to %r: telemetry must use https "
  65. "(or a localhost http endpoint for testing).",
  66. endpoint,
  67. )
  68. return SendConfig(enabled=enabled, send=False, endpoint=endpoint)
  69. return SendConfig(enabled=enabled, send=send_requested, endpoint=endpoint)