From 9c576fc69dc14df6f9416aab6e6b03b41bed20cc Mon Sep 17 00:00:00 2001 From: Victor Kyriazakos Date: Tue, 8 Sep 2026 14:14:47 +0000 Subject: [PATCH 01/13] fix(relay): honor explicit profile disable before automatic relay activity Relay bootstrap treated endpoint availability as activation, bypassing the platform configuration's explicit opt-out. An injected relay URL could provision credentials from a native-only profile and suppress its native connectors even when relay was disabled. Reuse the gateway's platform merge and boolean normalization for the explicit-disable decision. Guard registration overrides, discovery, media, and all dial/retry entrypoints; preserve URL-only legacy activation and explicit operator enrollment. Skip relay-exclusive native suppression for an opted-out relay. Add real-config startup and standalone regression coverage, including inherited credentials, managed config, config precedence, native delivery, and fresh-token retry. Document restart semantics without claiming live socket teardown. --- gateway/config_env.py | 6 +- gateway/relay/__init__.py | 43 ++- gateway/relay/adapter.py | 9 + gateway/relay/media.py | 8 +- gateway/relay/ws_transport.py | 17 +- gateway/run_startup.py | 3 +- tests/gateway/relay/test_explicit_disable.py | 267 +++++++++++++++++++ website/docs/user-guide/messaging/relay.md | 28 +- 8 files changed, 370 insertions(+), 11 deletions(-) create mode 100644 tests/gateway/relay/test_explicit_disable.py diff --git a/gateway/config_env.py b/gateway/config_env.py index a1e80ec0be..b5cf0c5e0e 100644 --- a/gateway/config_env.py +++ b/gateway/config_env.py @@ -450,7 +450,11 @@ def _relay(config: GatewayConfig) -> None: relay_url_yaml = str(existing_relay.extra.get("relay_url") or "").strip() if existing_relay else "" relay_url_val = relay_url_env or relay_url_yaml if relay_url_val: - _enable_from_env(config, Platform.RELAY).extra["relay_url"] = relay_url_val.rstrip("/") + relay_config = _enable_from_env(config, Platform.RELAY) + relay_config.extra["relay_url"] = relay_url_val.rstrip("/") + # An opted-out relay does not own this profile's native connections. + if not relay_config.enabled: + return if not relay_url_env or is_truthy_value(getenv("GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS")): return diff --git a/gateway/relay/__init__.py b/gateway/relay/__init__.py index 2366cf943c..14cc29b68a 100644 --- a/gateway/relay/__init__.py +++ b/gateway/relay/__init__.py @@ -6,7 +6,8 @@ hands it at handshake, and the production ``WebSocketRelayTransport``. The publi API MAY CHANGE without a deprecation cycle until >=2 real Class-1 platforms have shaken out the schema (``docs/relay-connector-contract.md``). Activation is config-driven: the relay platform is registered when a connector relay URL is set -(``GATEWAY_RELAY_URL`` env or ``gateway.relay_url``), like ``gateway.proxy_url``. +(``GATEWAY_RELAY_URL`` env or ``gateway.relay_url``), like ``gateway.proxy_url``, +unless the effective relay platform configuration explicitly disables it. """ from __future__ import annotations @@ -69,8 +70,39 @@ def _env_or_cfg_url(env_var: str, cfg_key: str) -> Optional[str]: return _env_or_cfg(env_var, cfg_key).rstrip("/") or None +def relay_explicitly_disabled() -> bool: + """The profile's normalized opt-out, before any URL/credential activation. + + Reuse the gateway's platform merge and boolean normalization without running + its env/plugin side effects. Absence is not a disable: URL-only deployments + predate the platform flag. The raw loader includes managed configuration. + """ + from gateway.config import Platform, PlatformConfig + from gateway.config_loader import ( + bridge_platform_shared_keys, load_legacy_gateway_json, merge_platform_sections, + ) + from hermes_constants import get_hermes_home + + cfg = _load_cfg() + data = load_legacy_gateway_json(get_hermes_home()) + platforms = merge_platform_sections(cfg, cfg.get("gateway"), data) + gateway = cfg.get("gateway") or {} + bridge_platform_shared_keys( + cfg, gateway.get("platforms") if isinstance(gateway, dict) else None, + data, platforms, [Platform.RELAY], + ) + block = platforms.get("relay") + return ( + isinstance(block, dict) + and "enabled" in block + and not PlatformConfig.from_dict(block).enabled + ) + + def relay_url() -> Optional[str]: - """The connector relay endpoint URL, or None. A non-empty value activates the relay platform.""" + """Effective connector URL; an explicit platform disable vetoes even an env URL.""" + if relay_explicitly_disabled(): + return None return _env_or_cfg_url("GATEWAY_RELAY_URL", "relay_url") @@ -97,6 +129,8 @@ def relay_fronted_platforms() -> set[str]: Same env source the live adapter's identity set comes from, so config-time validation (cron delivery preflight) and fire-time routing can never disagree — and it needs no live adapter, so a standalone scheduler can use it.""" + if relay_explicitly_disabled(): + return set() return {p for p, _ in relay_platform_identities() if p != "relay"} @@ -591,9 +625,12 @@ def send_relay_policy() -> bool: def register_relay_adapter(force: bool = False, url: Optional[str] = None) -> bool: """Register the generic ``relay`` platform when a relay URL is configured (or - ``force=True`` for tests: transport-less adapter). Returns True if registered. + ``force=True`` for tests: transport-less adapter). Neither overrides an + explicit profile disable. Returns True if registered. With a URL the factory builds a live ``WebSocketRelayTransport``; the adapter negotiates the real ``CapabilityDescriptor`` at ``connect()``.""" + if relay_explicitly_disabled(): + return False resolved_url = url if url is not None else relay_url() if not (force or resolved_url): return False diff --git a/gateway/relay/adapter.py b/gateway/relay/adapter.py index 111959bb32..b2ac6d753a 100644 --- a/gateway/relay/adapter.py +++ b/gateway/relay/adapter.py @@ -738,6 +738,11 @@ class RelayAdapter(BasePlatformAdapter): # ── abstract methods (delegated to the transport) ──────────────────── async def connect(self, *, is_reconnect: bool = False) -> bool: + from gateway.relay import relay_explicitly_disabled + + if relay_explicitly_disabled(): + self._set_fatal_error("relay_disabled", "Relay explicitly disabled in config", retryable=False) + return False # ``is_reconnect`` is part of the BasePlatformAdapter.connect contract (the # reconnect watcher passes it; refusing the kwarg would break recovery). # Relay IGNORES it: messages buffered during a gap live in the CONNECTOR's @@ -1697,6 +1702,10 @@ class RelayAdapter(BasePlatformAdapter): """Lazily build the authenticated /relay/media client from the SAME dial URL and per-gateway creds the WS uses; None when unavailable (media lanes then degrade to their pre-media fallbacks).""" + from gateway.relay import relay_explicitly_disabled + + if relay_explicitly_disabled(): + return None if self._media_client is not None: return self._media_client try: diff --git a/gateway/relay/media.py b/gateway/relay/media.py index 4b957f4165..0045424f14 100644 --- a/gateway/relay/media.py +++ b/gateway/relay/media.py @@ -60,7 +60,9 @@ class RelayMediaClient: @property def enabled(self) -> bool: """True when the client can authenticate (per-gateway creds present).""" - return bool(self._base_url and self._gateway_id and self._secret) + from gateway.relay import relay_explicitly_disabled + + return bool(self._base_url and self._gateway_id and self._secret) and not relay_explicitly_disabled() def _bearer(self) -> str: return make_upgrade_token(self._gateway_id, self._secret) @@ -115,7 +117,9 @@ class RelayMediaClient: The bearer is presented only for connector re-host URLs; public URLs (e.g. a Discord CDN pass-through) are fetched without it. """ - if not url: + from gateway.relay import relay_explicitly_disabled + + if not url or relay_explicitly_disabled(): return None needs_auth = self.is_relay_media_url(url) if needs_auth and not self.enabled: diff --git a/gateway/relay/ws_transport.py b/gateway/relay/ws_transport.py index f6bdaa97d5..55ea2bcf5c 100644 --- a/gateway/relay/ws_transport.py +++ b/gateway/relay/ws_transport.py @@ -305,6 +305,10 @@ async def _await_bounded(aw: Awaitable[Any]) -> None: REDIAL_HOLD_MAX_S = 60.0 +class _RelayDisabled(RuntimeError): + """Local profile opt-out is terminal, not a transient dial failure.""" + + class WebSocketRelayTransport: """RelayTransport over a WebSocket connection the gateway dials to the connector.""" @@ -408,12 +412,19 @@ class WebSocketRelayTransport: # ── lifecycle ──────────────────────────────────────────────────────── async def connect(self) -> bool: - await self._dial_and_start() + try: + await self._dial_and_start() + except _RelayDisabled: + return False return True async def _dial_and_start(self) -> None: """Open the socket, start the reader, send hello(s). Used by connect() and by the reconnect supervisor / fresh-token retry on a re-dial.""" + from gateway.relay import relay_explicitly_disabled + + if relay_explicitly_disabled(): + raise _RelayDisabled("Relay explicitly disabled in config") self._descriptor_ready = asyncio.get_running_loop().create_future() self._dial_generation += 1 # Fresh handshake generation: a reconnected connector re-sends one @@ -823,6 +834,8 @@ class WebSocketRelayTransport: try: await self._dial_and_start() logger.info("relay ws re-dialed with a fresh upgrade token after 4401") + except _RelayDisabled: + return except asyncio.CancelledError: raise except Exception as exc: # noqa: BLE001 - fall back to the backoff supervisor @@ -872,6 +885,8 @@ class WebSocketRelayTransport: await self._dial_and_start() logger.info("relay ws reconnected") return + except _RelayDisabled: + return except Exception as exc: # noqa: BLE001 - keep retrying on dial failure if self._latch_if_fresh_token_refused(exc): return diff --git a/gateway/run_startup.py b/gateway/run_startup.py index 29fd2c252f..47f02b3141 100644 --- a/gateway/run_startup.py +++ b/gateway/run_startup.py @@ -869,7 +869,8 @@ class GatewayStartupMixin: with _log_suppressed(logging.WARNING, "plugin discovery failed at gateway startup", exc_info=True): from hermes_cli.plugins import discover_plugins discover_plugins() - # Generic relay adapter only if GATEWAY_RELAY_URL / gateway.relay_url is set; no URL -> no-op. + # Relay entrypoints share the effective profile opt-out, including when a + # deployment injects a URL. No URL or explicitly disabled -> no side effects. try: from gateway.relay import ( register_relay_adapter, relay_url, self_provision_relay, send_relay_policy diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py new file mode 100644 index 0000000000..651696180e --- /dev/null +++ b/tests/gateway/relay/test_explicit_disable.py @@ -0,0 +1,267 @@ +"""Explicit relay opt-out must dominate ambient deployment credentials. + +Real profile files and production startup/standalone entrypoints; only external +I/O and unrelated gateway services are replaced. No connector is contacted. +""" +from types import SimpleNamespace +from unittest.mock import AsyncMock, Mock +import json +import os + +import pytest +import yaml + +import gateway.relay as relay +from gateway.config import Platform, PlatformConfig, load_gateway_config +from gateway.platform_registry import platform_registry +from gateway.relay.adapter import RelayAdapter +from gateway.relay.descriptor import CapabilityDescriptor, CONTRACT_VERSION +from gateway.relay.media import RelayMediaClient +from gateway.relay.ws_transport import WebSocketRelayTransport +from gateway.run_startup import GatewayStartupMixin + +URL = "wss://connector.example/relay" +CREDENTIALS = { + "GATEWAY_RELAY_ID": "shared-gateway", + "GATEWAY_RELAY_INSTANCE_ID": "shared-instance", + "GATEWAY_RELAY_DELIVERY_KEY": "inherited-delivery-key", +} + + +@pytest.fixture +def profile(tmp_path, monkeypatch): + monkeypatch.setenv("HERMES_HOME", str(tmp_path)) + # Keep the runtime loader on the same real profile as load_gateway_config. + monkeypatch.setattr("gateway.run._hermes_home", tmp_path) + for key in list(os.environ): + if key.startswith("GATEWAY_RELAY_"): + monkeypatch.delenv(key) + for key, value in CREDENTIALS.items(): + monkeypatch.setenv(key, value) + monkeypatch.setenv("GATEWAY_RELAY_PLATFORMS", "slack") + monkeypatch.setattr("hermes_cli.plugins.discover_plugins", lambda: None) + monkeypatch.setattr(GatewayStartupMixin, "_register_config_hooks", lambda *a, **k: None) + platform_registry.unregister("relay") + yield tmp_path + platform_registry.unregister("relay") + + +def configure(home, state, source, monkeypatch): + cfg = {"platforms": {"slack": {"enabled": True, "token": "native-test-token"}}, + "slack": {"require_mention": False}} + if state is not None: + cfg["platforms"]["relay"] = {"enabled": state, "extra": {"relay_url": URL}} + if source == "env": + monkeypatch.setenv("GATEWAY_RELAY_URL", URL) + elif source == "managed": + managed = home / "managed" + managed.mkdir() + (managed / "config.yaml").write_text(yaml.safe_dump({"gateway": {"relay_url": URL}})) + monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) + else: + cfg["gateway"] = {"relay_url": URL} + (home / "config.yaml").write_text(yaml.safe_dump(cfg), encoding="utf-8") + + +def descriptor(): + return CapabilityDescriptor(contract_version=CONTRACT_VERSION, platform="slack", + label="Relay", max_message_length=4096, + supports_draft_streaming=False, supports_edit=True, + supports_threads=False, markdown_dialect="plain", len_unit="chars") + + +@pytest.mark.asyncio +@pytest.mark.parametrize("state", [False, True, None], ids=["disabled", "enabled", "legacy"]) +@pytest.mark.parametrize("source", ["yaml", "env", "managed"]) +@pytest.mark.parametrize("pinned", [False, True], ids=["unprovisioned", "inherited-secret"]) +async def test_production_startup_respects_profile_opt_out(profile, monkeypatch, state, source, pinned): + configure(profile, state, source, monkeypatch) + if state is True: + # The winning top-level enable must override a lower-priority disable. + path = profile / "config.yaml" + cfg = yaml.safe_load(path.read_text()) + cfg.setdefault("gateway", {})["platforms"] = {"relay": {"enabled": False}} + path.write_text(yaml.safe_dump(cfg)) + if pinned: + monkeypatch.setenv("GATEWAY_RELAY_SECRET", "a" * 64) + before = {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} + token = Mock(return_value="identity-token") + provision = Mock(return_value={"gatewayId": "provisioned-gateway", "secret": "b" * 64, + "deliveryKey": "new-delivery-key"}) + policy = Mock(return_value=200) + monkeypatch.setattr(relay, "_resolve_relay_identity_token", token) + monkeypatch.setattr(relay, "_post_provision", provision) + monkeypatch.setattr(relay, "_post_policy", policy) + relay_connect = AsyncMock(return_value=True) + monkeypatch.setattr(WebSocketRelayTransport, "connect", relay_connect) + monkeypatch.setattr(WebSocketRelayTransport, "handshake", AsyncMock(return_value=descriptor())) + monkeypatch.setattr(RelayAdapter, "_start_revocation_monitor", lambda self: None) + native = SimpleNamespace(connect=AsyncMock(return_value=True), send_path_degraded=False) + + # Execute start(), including real relay bootstrap, prefilter, connect and + # aggregation. Suppress only unrelated recovery/watchers/status services. + runner = GatewayStartupMixin() + runner.config = load_gateway_config() + runner.adapters = {} + runner._failed_platforms = {} + runner.delivery_router = SimpleNamespace(adapters={}) + for name in ("_start_install_faulthandler", "_start_log_startup_environment", + "_start_startup_warmup", "_wire_adapter_handlers", "_update_platform_runtime_status", + "_wire_teams_pipeline_runtime", "_install_plugin_message_injector", + "_update_runtime_status", "_start_spawn_background_watchers"): + monkeypatch.setattr(runner, name, Mock(), raising=False) + runner._start_check_access_policy = lambda: False + runner._abort_startup_if_shutdown_requested = AsyncMock(return_value=False) + runner._multiplex_on = lambda: False + runner._startup_should_abort = lambda: False + + async def recover(): + runner._start_register_plugins_relay_hooks() + + async def connect(adapter, platform): + return await adapter.connect() + + async def secondary(count, skipped): + return False, count + + runner._start_recover_previous_run = recover + runner._connect_initial_adapter_with_timeout = connect + runner._start_secondary_profiles = secondary + runner._start_finish_wiring = AsyncMock() + runner._start_handle_no_connections = lambda *args: False + runner._publish_primary_adapter = lambda p, a: runner.adapters.__setitem__(p, a) + runner._create_adapter = lambda p, c: (platform_registry.create_adapter("relay", c) + if p == Platform.RELAY else native) + assert await runner.start() is True + + if state is False: + token.assert_not_called() + provision.assert_not_called() + policy.assert_not_called() + relay_connect.assert_not_awaited() + assert not platform_registry.is_registered("relay") + assert Platform.RELAY not in runner.adapters + assert Platform.RELAY not in runner._failed_platforms + assert {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} == before + native.connect.assert_awaited_once() + assert runner.adapters[Platform.SLACK] is native + from cron.scheduler_delivery import _resolve_target_transport + + resolved, error = _resolve_target_transport( + {"id": "native-job"}, Platform.SLACK, "slack", {"chat_id": "channel"}, {}, runner.config, + ) + assert error is None + assert resolved[1] is runner.config.platforms[Platform.SLACK] + else: + assert platform_registry.is_registered("relay") + assert provision.call_count == (0 if pinned else 1) + assert token.call_count == provision.call_count + policy.assert_called_once() + # Existing env-exclusive behavior is unchanged. YAML activation is additive. + assert native.connect.await_count == (0 if source == "env" else 1) + # The env path already auto-enables relay in the platform loader. + if source == "env" or state is True: + relay_connect.assert_awaited_once() + assert Platform.RELAY in runner.adapters + if source == "env": + from cron.scheduler_delivery import _resolve_target_transport + + resolved, error = _resolve_target_transport( + {"id": "relay-job"}, Platform.SLACK, "slack", {"chat_id": "channel"}, {}, runner.config, + ) + assert resolved is None + assert "relay-fronted" in error + + +@pytest.mark.asyncio +@pytest.mark.parametrize("entry", ["url", "provision", "policy", "registration", "forced-registration", + "fronted", "adapter-connect", "adapter-reconnect", + "transport-connect", "transport-reconnect", "fresh-token", "media-hook", + "cached-media-hook", "upload", "download", "public-download"]) +@pytest.mark.parametrize("spelling", ["top", "nested", "normalized", "legacy-json", "yaml-wins", "gateway-relay", "top-relay", "managed-disable", "sibling-keeps-disable"]) +async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, monkeypatch, entry, spelling): + block = {"enabled": "false" if spelling == "normalized" else False} + cfg = {"gateway": {"relay_url": URL}} + if spelling == "nested": + cfg["gateway"]["platforms"] = {"relay": block} + elif spelling == "gateway-relay": + cfg["gateway"]["relay"] = block + cfg["platforms"] = {"relay": {"enabled": True}} + elif spelling == "top-relay": + cfg["relay"] = block + cfg["gateway"]["relay"] = {"enabled": True} + elif spelling == "legacy-json": + (profile / "gateway.json").write_text(json.dumps({"platforms": {"relay": block}})) + elif spelling == "managed-disable": + cfg["platforms"] = {"relay": {"enabled": True}} + managed = profile / "managed" + managed.mkdir() + (managed / "config.yaml").write_text(yaml.safe_dump({"platforms": {"relay": block}})) + monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) + elif spelling == "sibling-keeps-disable": + cfg["gateway"]["platforms"] = {"relay": block} + cfg["platforms"] = {"relay": {"extra": {"relay_url": URL}}} + else: + cfg["platforms"] = {"relay": block} + if spelling == "yaml-wins": + cfg["gateway"]["platforms"] = {"relay": {"enabled": True}} + (profile / "config.yaml").write_text(yaml.safe_dump(cfg), encoding="utf-8") + monkeypatch.setenv("GATEWAY_RELAY_URL", URL) + monkeypatch.setenv("GATEWAY_RELAY_IDP_TOKEN_URL", "https://identity.example/token") + before = {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} + http = Mock(side_effect=AssertionError("disabled relay attempted HTTP")) + monkeypatch.setattr("urllib.request.urlopen", http) + provision = Mock(return_value={"secret": "b" * 64, "gatewayId": "replaced"}) + monkeypatch.setattr(relay, "_post_provision", provision) + transport = SimpleNamespace(connect=AsyncMock(return_value=True), + handshake=AsyncMock(return_value=descriptor()), + set_inbound_handler=Mock()) + adapter = RelayAdapter(PlatformConfig(enabled=True), descriptor(), transport=transport) + media = RelayMediaClient("https://connector.example", "shared-gateway", "a" * 64) + file = profile / "attachment.txt" + file.write_text("attachment", encoding="utf-8") + + if entry == "url": + assert relay.relay_url() is None + elif entry == "provision": + assert relay.self_provision_relay() is False + elif entry == "policy": + monkeypatch.setenv("GATEWAY_RELAY_SECRET", "a" * 64) + before["GATEWAY_RELAY_SECRET"] = "a" * 64 + monkeypatch.setenv("SLACK_ALLOW_BOTS", "all") + assert relay.send_relay_policy() is False + elif entry in {"registration", "forced-registration"}: + assert relay.register_relay_adapter(url=URL, force=entry == "forced-registration") is False + assert not platform_registry.is_registered("relay") + elif entry == "fronted": + assert relay.relay_fronted_platforms() == set() + elif entry in {"adapter-connect", "adapter-reconnect"}: + assert await adapter.connect(is_reconnect=entry == "adapter-reconnect") is False + transport.connect.assert_not_awaited() + transport.set_inbound_handler.assert_not_called() + elif entry in {"transport-connect", "transport-reconnect", "fresh-token"}: + ws = WebSocketRelayTransport(URL, "slack", "bot", reconnect_backoff_s=0) + dial = AsyncMock() + monkeypatch.setattr("gateway.relay.ws_transport.websockets.connect", dial) + if entry == "transport-connect": + assert await ws.connect() is False + elif entry == "fresh-token": + await ws._redial_with_fresh_token() + else: + await ws._reconnect_loop() + dial.assert_not_awaited() + assert ws._reader is None + assert ws._supervisor is None + elif entry in {"media-hook", "cached-media-hook"}: + if entry == "cached-media-hook": + adapter._media_client = media + assert adapter._get_media_client() is None + elif entry == "upload": + assert await media.upload(str(file)) is None + else: + url = "https://connector.example/relay/media/id" if entry == "download" else "https://cdn.example/file" + assert await media.download(url) is None + + http.assert_not_called() + provision.assert_not_called() + assert {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} == before diff --git a/website/docs/user-guide/messaging/relay.md b/website/docs/user-guide/messaging/relay.md index d12ae3edc5..8767cfdece 100644 --- a/website/docs/user-guide/messaging/relay.md +++ b/website/docs/user-guide/messaging/relay.md @@ -96,12 +96,34 @@ environment. ## Configuration -Relay activates when a connector relay URL is configured — there is no -separate feature flag. Deployments that don't set it are unaffected. +Relay activation remains URL-based for compatibility, unless the effective +platform configuration explicitly disables it: + +```yaml +platforms: + relay: + enabled: false +``` + +- **Explicit disable wins.** `enabled: false` prevents automatic identity-token + resolution, provisioning, credential mutation, registration, policy calls, + connection attempts, reconnects, and relay media handling, even with an + injected `gateway.relay_url` or `GATEWAY_RELAY_URL`. +- **Native platforms remain available.** A disabled relay does not suppress + native messaging adapters or claim standalone delivery destinations through + inherited relay identity variables. Inherited credentials are left unchanged. +- **Existing activation is preserved.** `enabled: true` still requires a + connector URL. Omitting `enabled` keeps the existing URL-based behavior. + +The decision uses the gateway's merged platform configuration, including managed +settings and supported nested platform sections. Restart the gateway after +changing this setting. This is not a live teardown mechanism for an already-open +socket. The explicit `hermes gateway enroll` command remains available while +runtime relay is disabled. | Setting | Where | Meaning | |---------|-------|---------| -| `GATEWAY_RELAY_URL` | env (`~/.hermes/.env`) | Connector relay WebSocket URL. Presence enables the relay platform. | +| `GATEWAY_RELAY_URL` | env (`~/.hermes/.env`) | Connector relay WebSocket URL. Enables relay unless explicitly disabled in platform configuration. | | `gateway.relay_url` | `config.yaml` | Same as above, config-file form (env takes precedence). | | `GATEWAY_RELAY_ID` | env | This gateway instance's id (written by `enroll`). | | `GATEWAY_RELAY_SECRET` | env | Per-gateway secret authenticating the WebSocket upgrade (written by `enroll`). | From f2de1028728846107f5663a5ff8b15d7f6effddf Mon Sep 17 00:00:00 2001 From: Victor Kyriazakos Date: Tue, 8 Sep 2026 14:30:32 +0000 Subject: [PATCH 02/13] fix(relay): preserve legacy opt-out without standalone bootstrap Carry legacy relay enabled intent through the canonical env sweep without changing other platforms. Read opt-out config through the cached non-bootstrap reader and existing managed overlay. Reproduce both Salt findings before fixes, cover native startup/delivery and isolated cold imports, and mutation-check the regressions. --- gateway/config_loader.py | 8 +++ gateway/relay/__init__.py | 8 ++- tests/gateway/relay/test_cold_opt_out.py | 66 ++++++++++++++++++++ tests/gateway/relay/test_explicit_disable.py | 52 ++++++++++++++- 4 files changed, 131 insertions(+), 3 deletions(-) create mode 100644 tests/gateway/relay/test_cold_opt_out.py diff --git a/gateway/config_loader.py b/gateway/config_loader.py index df8f5f6382..e076336ba7 100644 --- a/gateway/config_loader.py +++ b/gateway/config_loader.py @@ -27,6 +27,14 @@ def load_legacy_gateway_json(home: Path) -> Any: try: with open(path, "r", encoding="utf-8") as f: data = json.load(f) or {} + # Relay accepts a legacy opt-out as authoritative, just like YAML. + # Preserve that intent through credential activation and the exclusive + # native-adapter sweep, even when config.yaml is missing. Other legacy + # platforms retain their existing env-driven enablement semantics. + platforms = data.get("platforms") if isinstance(data, dict) else None + relay = platforms.get("relay") if isinstance(platforms, dict) else None + if isinstance(relay, dict) and "enabled" in relay: + _dict_slot(relay, "extra")["_enabled_explicit"] = True logger.info("Loaded legacy %s — consider moving settings to config.yaml", path) return data except Exception as e: diff --git a/gateway/relay/__init__.py b/gateway/relay/__init__.py index 14cc29b68a..f0fbfa7c7d 100644 --- a/gateway/relay/__init__.py +++ b/gateway/relay/__init__.py @@ -82,8 +82,14 @@ def relay_explicitly_disabled() -> bool: bridge_platform_shared_keys, load_legacy_gateway_json, merge_platform_sections, ) from hermes_constants import get_hermes_home + from hermes_cli.config import read_raw_config + from hermes_cli.managed_scope import apply_managed_overlay - cfg = _load_cfg() + # Do not import gateway.run here: standalone routing must not bootstrap + # runtime flags, config-to-env bridges or dotenv. The shared cached reader + # resolves the context-local home; the same managed overlay is used by the + # runtime loader, without introducing CLI defaults into platform precedence. + cfg = apply_managed_overlay(read_raw_config()) data = load_legacy_gateway_json(get_hermes_home()) platforms = merge_platform_sections(cfg, cfg.get("gateway"), data) gateway = cfg.get("gateway") or {} diff --git a/tests/gateway/relay/test_cold_opt_out.py b/tests/gateway/relay/test_cold_opt_out.py new file mode 100644 index 0000000000..fcf7ac768b --- /dev/null +++ b/tests/gateway/relay/test_cold_opt_out.py @@ -0,0 +1,66 @@ +"""Standalone relay routing must not bootstrap the gateway or reload secrets.""" +import json +import os +from pathlib import Path +import subprocess +import sys +import textwrap + +import pytest +import yaml + + +@pytest.mark.parametrize("case", ["native", "url-only", "disabled", "managed", "scoped", "scoped-json"]) +def test_cold_fronted_platforms_is_read_only(tmp_path, case): + home = tmp_path / "primary" + home.mkdir() + scoped = tmp_path / "secondary" + scoped.mkdir() + managed = tmp_path / "managed" + managed.mkdir() + config = {"platforms": {"relay": {"enabled": True}}} + if case == "disabled": + config["platforms"]["relay"]["enabled"] = False + if case not in {"native", "url-only"}: + (home / "config.yaml").write_text(yaml.safe_dump(config)) + if case == "managed": + (managed / "config.yaml").write_text("platforms:\n relay:\n enabled: false\n") + if case == "scoped": + (scoped / "config.yaml").write_text("platforms:\n relay:\n enabled: false\n") + elif case == "scoped-json": + (scoped / "gateway.json").write_text(json.dumps({"platforms": {"relay": {"enabled": False}}})) + for root in (home, scoped): + (root / ".env").write_text("GATEWAY_RELAY_SECRET=dotenv-only-test-secret\n") + # Allowlist only: never inherit live credentials, profile selectors, or + # pytest's imported modules. HOME and cwd are temporary as well as HERMES_HOME. + env = {k: os.environ[k] for k in ("PATH", "SYSTEMROOT", "WINDIR") if k in os.environ} + env.update({"HOME": str(tmp_path), "USERPROFILE": str(tmp_path), + "HERMES_HOME": str(home), "HERMES_MANAGED_DIR": str(managed), + "PYTHONPATH": str(Path(__file__).resolve().parents[3]), + "PYTHONDONTWRITEBYTECODE": "1", "PYTHONUTF8": "1"}) + if case != "native": + env.update({"GATEWAY_RELAY_URL": "wss://connector.example/relay", + "GATEWAY_RELAY_PLATFORMS": "slack", + "GATEWAY_RELAY_SECRET": "inherited-test-secret"}) + code = textwrap.dedent(""" + import json, os, sys + from hermes_constants import set_hermes_home_override + if sys.argv[1].startswith("scoped"): + set_hermes_home_override(sys.argv[2]) + before = dict(os.environ) + assert "gateway.run" not in sys.modules + from gateway.relay import relay_fronted_platforms + fronted = relay_fronted_platforms() + changed = {k: [before.get(k), os.environ.get(k)] + for k in before.keys() | os.environ.keys() + if before.get(k) != os.environ.get(k)} + print(json.dumps({"fronted": sorted(fronted), + "bootstrapped": "gateway.run" in sys.modules, + "changed_env": changed})) + """) + child = subprocess.run([sys.executable, "-c", code, case, str(scoped)], + cwd=tmp_path, env=env, text=True, capture_output=True, timeout=45) + assert child.returncode == 0, child.stderr + observed = json.loads(child.stdout.splitlines()[-1]) + assert observed == {"fronted": ["slack"] if case == "url-only" else [], + "bootstrapped": False, "changed_env": {}} diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py index 651696180e..ce366e3646 100644 --- a/tests/gateway/relay/test_explicit_disable.py +++ b/tests/gateway/relay/test_explicit_disable.py @@ -51,7 +51,10 @@ def configure(home, state, source, monkeypatch): "slack": {"require_mention": False}} if state is not None: cfg["platforms"]["relay"] = {"enabled": state, "extra": {"relay_url": URL}} - if source == "env": + if source == "legacy-json": + (home / "gateway.json").write_text(json.dumps({"platforms": cfg.pop("platforms")})) + monkeypatch.setenv("GATEWAY_RELAY_URL", URL) + elif source == "env": monkeypatch.setenv("GATEWAY_RELAY_URL", URL) elif source == "managed": managed = home / "managed" @@ -96,7 +99,8 @@ async def test_production_startup_respects_profile_opt_out(profile, monkeypatch, monkeypatch.setattr(WebSocketRelayTransport, "connect", relay_connect) monkeypatch.setattr(WebSocketRelayTransport, "handshake", AsyncMock(return_value=descriptor())) monkeypatch.setattr(RelayAdapter, "_start_revocation_monitor", lambda self: None) - native = SimpleNamespace(connect=AsyncMock(return_value=True), send_path_degraded=False) + native = SimpleNamespace(connect=AsyncMock(return_value=True), send_path_degraded=False, + send=AsyncMock(return_value={"success": True})) # Execute start(), including real relay bootstrap, prefilter, connect and # aggregation. Suppress only unrelated recovery/watchers/status services. @@ -152,6 +156,16 @@ async def test_production_startup_respects_profile_opt_out(profile, monkeypatch, ) assert error is None assert resolved[1] is runner.config.platforms[Platform.SLACK] + # Deliver through the native adapter published by real startup, not just + # a helper predicate. Standalone routing above must also remain enabled. + resolved, error = _resolve_target_transport( + {"id": "native-job"}, Platform.SLACK, "slack", {"chat_id": "channel"}, + runner.adapters, runner.config, + ) + assert error is None + assert not resolved[0].is_relay + assert await resolved[0].send(Platform.SLACK, "channel", "native receipt", {}) == {"success": True} + native.send.assert_awaited_once_with("channel", "native receipt", metadata={}) else: assert platform_registry.is_registered("relay") assert provision.call_count == (0 if pinned else 1) @@ -173,6 +187,40 @@ async def test_production_startup_respects_profile_opt_out(profile, monkeypatch, assert "relay-fronted" in error +@pytest.mark.asyncio +@pytest.mark.parametrize("pinned", [False, True], ids=["unprovisioned", "inherited-secret"]) +async def test_legacy_json_disable_preserves_startup_and_native_delivery(profile, monkeypatch, pinned): + await test_production_startup_respects_profile_opt_out( + profile, monkeypatch, False, "legacy-json", pinned, + ) + + +@pytest.mark.parametrize("yaml_state", ["absent", "empty", "sibling", "enabled"]) +@pytest.mark.parametrize("disabled", [False, "false"]) +def test_legacy_json_disable_agrees_with_normalized_config(profile, monkeypatch, yaml_state, disabled): + (profile / "gateway.json").write_text(json.dumps({"platforms": { + "relay": {"enabled": disabled}, + "slack": {"enabled": True, "token": "native-test-token"}, + "telegram": {"enabled": False}, + }})) + cfg = {} + if yaml_state == "sibling": + cfg = {"platforms": {"relay": {"extra": {"relay_url": URL}}}} + elif yaml_state == "enabled": + cfg = {"platforms": {"relay": {"enabled": True}}} + if yaml_state != "absent": + (profile / "config.yaml").write_text(yaml.safe_dump(cfg)) + monkeypatch.setenv("GATEWAY_RELAY_URL", URL) + monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "native-telegram-test-token") + # Other legacy platforms keep their existing credential-driven enablement. + monkeypatch.setenv("GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS", "true") + config = load_gateway_config() + assert relay.relay_explicitly_disabled() is (yaml_state != "enabled") + assert config.platforms[Platform.RELAY].enabled is (yaml_state == "enabled") + assert config.platforms[Platform.SLACK].enabled + assert config.platforms[Platform.TELEGRAM].enabled + + @pytest.mark.asyncio @pytest.mark.parametrize("entry", ["url", "provision", "policy", "registration", "forced-registration", "fronted", "adapter-connect", "adapter-reconnect", From 6ce2b72281c85be13ea66d801680310040333add Mon Sep 17 00:00:00 2001 From: Victor Kyriazakos Date: Tue, 8 Sep 2026 14:42:54 +0000 Subject: [PATCH 03/13] fix: apply managed gateway config without user YAML Read an empty raw user layer on absent, invalid or unreadable YAML before applying the existing managed overlay. Preserve raw defaults and platform precedence so managed relay opt-out prevents env-exclusive native suppression. Prove absent-YAML startup/native routing, managed enabled and URL-only controls, managed leaf precedence, and invalid-file siblings. Mutation: 17 failed/30 passed. Canonical 50-file suite: 682 passed. --- gateway/config_loader.py | 25 ++++--- tests/gateway/relay/test_cold_opt_out.py | 6 +- tests/gateway/relay/test_explicit_disable.py | 77 ++++++++++++++++++-- 3 files changed, 89 insertions(+), 19 deletions(-) diff --git a/gateway/config_loader.py b/gateway/config_loader.py index e076336ba7..a5f147b9f0 100644 --- a/gateway/config_loader.py +++ b/gateway/config_loader.py @@ -344,19 +344,22 @@ def bridge_core_env_settings(yaml_cfg: dict, platforms_data: dict) -> None: def load_yaml_layer(home: Path, gw_data: dict) -> None: - """Overlay ``config.yaml`` onto *gw_data* in place. Raises on any failure (caller warns + falls back).""" - import yaml - - config_yaml_path = home / "config.yaml" - if not config_yaml_path.exists(): - return - with open(config_yaml_path, encoding="utf-8") as f: - yaml_cfg = yaml.safe_load(f) or {} - - # Managed scope: overlay administrator-pinned values (this loader bypasses - # hermes_cli.config.load_config, so managed quick_commands / stt would otherwise be ignored). + """Overlay raw user + managed YAML onto *gw_data* without introducing CLI defaults.""" + from hermes_cli.config import read_user_config_raw from hermes_cli import managed_scope + + # Match the raw runtime/predicate readers: absent, unreadable or malformed + # user YAML is an empty layer, not a reason to skip administrator settings. + # Use the explicit home rather than a process-global path (multiplex-safe). + try: + yaml_cfg = read_user_config_raw(home / "config.yaml") + except Exception as e: + logger.warning("Failed to read %s; applying managed config over an empty user layer: %s", + home / "config.yaml", e) + yaml_cfg = {} yaml_cfg = managed_scope.apply_managed_overlay(yaml_cfg) + if not yaml_cfg: + return gateway_section = yaml_cfg.get("gateway") bridge_toplevel_keys(yaml_cfg, gateway_section, gw_data) diff --git a/tests/gateway/relay/test_cold_opt_out.py b/tests/gateway/relay/test_cold_opt_out.py index fcf7ac768b..b113739fa5 100644 --- a/tests/gateway/relay/test_cold_opt_out.py +++ b/tests/gateway/relay/test_cold_opt_out.py @@ -10,7 +10,7 @@ import pytest import yaml -@pytest.mark.parametrize("case", ["native", "url-only", "disabled", "managed", "scoped", "scoped-json"]) +@pytest.mark.parametrize("case", ["native", "url-only", "disabled", "managed", "managed-only", "scoped", "scoped-json"]) def test_cold_fronted_platforms_is_read_only(tmp_path, case): home = tmp_path / "primary" home.mkdir() @@ -21,9 +21,9 @@ def test_cold_fronted_platforms_is_read_only(tmp_path, case): config = {"platforms": {"relay": {"enabled": True}}} if case == "disabled": config["platforms"]["relay"]["enabled"] = False - if case not in {"native", "url-only"}: + if case not in {"native", "url-only", "managed-only"}: (home / "config.yaml").write_text(yaml.safe_dump(config)) - if case == "managed": + if case in {"managed", "managed-only"}: (managed / "config.yaml").write_text("platforms:\n relay:\n enabled: false\n") if case == "scoped": (scoped / "config.yaml").write_text("platforms:\n relay:\n enabled: false\n") diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py index ce366e3646..55019dc058 100644 --- a/tests/gateway/relay/test_explicit_disable.py +++ b/tests/gateway/relay/test_explicit_disable.py @@ -51,6 +51,20 @@ def configure(home, state, source, monkeypatch): "slack": {"require_mention": False}} if state is not None: cfg["platforms"]["relay"] = {"enabled": state, "extra": {"relay_url": URL}} + if source == "managed-only": + # No user YAML: the managed overlay must still own relay intent before + # the injected URL can exclusively suppress this legacy native Slack. + (home / "gateway.json").write_text(json.dumps({"platforms": {"slack": cfg["platforms"]["slack"]}})) + managed = home / "managed" + managed.mkdir() + managed_cfg: dict = {"gateway": {"relay_url": URL}, "slack": {"require_mention": False}} + if state is not None: + managed_cfg["platforms"] = {"relay": {"enabled": state}} + (managed / "config.yaml").write_text(yaml.safe_dump(managed_cfg)) + monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) + monkeypatch.setenv("GATEWAY_RELAY_URL", URL) + assert not (home / "config.yaml").exists() + return if source == "legacy-json": (home / "gateway.json").write_text(json.dumps({"platforms": cfg.pop("platforms")})) monkeypatch.setenv("GATEWAY_RELAY_URL", URL) @@ -75,11 +89,11 @@ def descriptor(): @pytest.mark.asyncio @pytest.mark.parametrize("state", [False, True, None], ids=["disabled", "enabled", "legacy"]) -@pytest.mark.parametrize("source", ["yaml", "env", "managed"]) +@pytest.mark.parametrize("source", ["yaml", "env", "managed", "managed-only"]) @pytest.mark.parametrize("pinned", [False, True], ids=["unprovisioned", "inherited-secret"]) async def test_production_startup_respects_profile_opt_out(profile, monkeypatch, state, source, pinned): configure(profile, state, source, monkeypatch) - if state is True: + if state is True and source != "managed-only": # The winning top-level enable must override a lower-priority disable. path = profile / "config.yaml" cfg = yaml.safe_load(path.read_text()) @@ -172,12 +186,12 @@ async def test_production_startup_respects_profile_opt_out(profile, monkeypatch, assert token.call_count == provision.call_count policy.assert_called_once() # Existing env-exclusive behavior is unchanged. YAML activation is additive. - assert native.connect.await_count == (0 if source == "env" else 1) + assert native.connect.await_count == (0 if source in {"env", "managed-only"} else 1) # The env path already auto-enables relay in the platform loader. - if source == "env" or state is True: + if source in {"env", "managed-only"} or state is True: relay_connect.assert_awaited_once() assert Platform.RELAY in runner.adapters - if source == "env": + if source in {"env", "managed-only"}: from cron.scheduler_delivery import _resolve_target_transport resolved, error = _resolve_target_transport( @@ -221,6 +235,59 @@ def test_legacy_json_disable_agrees_with_normalized_config(profile, monkeypatch, assert config.platforms[Platform.TELEGRAM].enabled +@pytest.mark.parametrize("user_yaml", ["no-files", "absent", "empty", "null", "list", "malformed", "unreadable", "sibling", "enabled", "disabled"]) +@pytest.mark.parametrize("managed_state", ["absent", "url-only", "enabled", "disabled"]) +def test_managed_layer_agrees_with_native_config(profile, monkeypatch, user_yaml, managed_state): + """Managed leaves override user leaves, not CLI defaults or a second merge policy.""" + path = profile / "config.yaml" + user_docs = { + "empty": "", "null": "null\n", "list": "- not-a-config\n", + "malformed": "platforms: [\n", + "sibling": "platforms:\n relay:\n extra:\n user_sibling: kept\n", + "enabled": "platforms:\n relay:\n enabled: true\n", + "disabled": "platforms:\n relay:\n enabled: false\n", + } + if user_yaml == "unreadable": + path.mkdir() # A directory fails open even when tests run as root. + elif user_yaml not in {"absent", "no-files"}: + path.write_text(user_docs[user_yaml]) + managed = profile / "managed" + managed.mkdir() + monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) + if managed_state != "absent": + block: dict = {"extra": {"relay_url": "${GATEWAY_RELAY_URL}", "managed_sibling": "pinned"}} + if managed_state != "url-only": + block["enabled"] = managed_state == "enabled" + (managed / "config.yaml").write_text(yaml.safe_dump({ + "platforms": {"relay": block}, + "gateway": {"max_concurrent_sessions": 7}, + })) + if user_yaml == "no-files": + monkeypatch.setenv("SLACK_BOT_TOKEN", "native-test-token") + else: + (profile / "gateway.json").write_text(json.dumps({"platforms": { + "slack": {"enabled": True, "token": "native-test-token"}, + "telegram": {"enabled": False}, + }})) + monkeypatch.setenv("GATEWAY_RELAY_URL", URL) + monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "native-telegram-test-token") + # An absent managed enabled leaf must not introduce DEFAULT_CONFIG's false. + disabled = managed_state == "disabled" or ( + managed_state in {"absent", "url-only"} and user_yaml == "disabled" + ) + config = load_gateway_config() + assert relay.relay_explicitly_disabled() is disabled + assert config.platforms[Platform.RELAY].enabled is not disabled + assert config.platforms[Platform.SLACK].enabled is disabled + assert config.platforms[Platform.TELEGRAM].enabled is disabled + if managed_state != "absent": + assert config.max_concurrent_sessions == 7 + assert config.platforms[Platform.RELAY].extra["managed_sibling"] == "pinned" + assert config.platforms[Platform.RELAY].extra["relay_url"] == URL + if user_yaml == "sibling": + assert config.platforms[Platform.RELAY].extra["user_sibling"] == "kept" + + @pytest.mark.asyncio @pytest.mark.parametrize("entry", ["url", "provision", "policy", "registration", "forced-registration", "fronted", "adapter-connect", "adapter-reconnect", From 114cfc0bc0a9075ac67dd0468be93b9e9ceb9fa2 Mon Sep 17 00:00:00 2001 From: Victor Kyriazakos Date: Tue, 8 Sep 2026 15:41:04 +0000 Subject: [PATCH 04/13] test(gateway): exercise streaming configuration with real YAML --- tests/test_gateway_streaming_nested_config.py | 58 +++++++++++-------- 1 file changed, 35 insertions(+), 23 deletions(-) diff --git a/tests/test_gateway_streaming_nested_config.py b/tests/test_gateway_streaming_nested_config.py index b4658b755a..8caed2ea09 100644 --- a/tests/test_gateway_streaming_nested_config.py +++ b/tests/test_gateway_streaming_nested_config.py @@ -1,42 +1,54 @@ """Regression test for #25676 — nested gateway.streaming config must be loaded.""" from pathlib import Path -from unittest.mock import patch, MagicMock +from textwrap import dedent + +import pytest - -def _load_with_yaml_dict(yaml_dict: dict): - """Patch filesystem so load_gateway_config() sees *yaml_dict* as config.yaml.""" +@pytest.fixture +def load_yaml(tmp_path, monkeypatch): + """Exercise the raw loader, not a particular YAML parser implementation.""" from gateway.config import load_gateway_config - fake_home = Path("/tmp/fake_hermes_home_25676") + monkeypatch.setattr(Path, "home", lambda: tmp_path) + monkeypatch.setenv("HERMES_HOME", str(tmp_path)) - def fake_exists(self): - return str(self).endswith("config.yaml") + def load(text): + (tmp_path / "config.yaml").write_text(dedent(text), encoding="utf-8") + return load_gateway_config() - with patch("gateway.config.get_hermes_home", return_value=fake_home), \ - patch.object(Path, "exists", fake_exists), \ - patch("builtins.open", create=True) as mock_file: - mock_file.return_value.__enter__ = lambda s: s - mock_file.return_value.__exit__ = MagicMock(return_value=False) - with patch("yaml.safe_load", return_value=yaml_dict): - return load_gateway_config() + return load class TestStreamingConfigNested: - def test_top_level_streaming(self): - cfg = _load_with_yaml_dict({"streaming": {"enabled": True, "transport": "draft"}}) + def test_top_level_streaming(self, load_yaml): + cfg = load_yaml("streaming: {enabled: true, transport: draft}") assert cfg.streaming.enabled is True assert cfg.streaming.transport == "draft" - def test_top_level_takes_precedence(self): - cfg = _load_with_yaml_dict({ - "streaming": {"enabled": True, "transport": "edit"}, - "gateway": {"streaming": {"enabled": False, "transport": "draft"}}, - }) + def test_top_level_takes_precedence(self, load_yaml): + cfg = load_yaml(""" + streaming: {enabled: true, transport: edit} + gateway: + streaming: {enabled: false, transport: draft} + """) assert cfg.streaming.enabled is True assert cfg.streaming.transport == "edit" + def test_nested_only_streaming(self, load_yaml): + cfg = load_yaml(""" + gateway: + streaming: {enabled: true, transport: draft} + """) + assert cfg.streaming.enabled is True + assert cfg.streaming.transport == "draft" + + def test_explicit_disable_preserves_transport(self, load_yaml): + cfg = load_yaml("streaming: {enabled: false, mode: auto, transport: draft}") + assert cfg.streaming.enabled is False + assert cfg.streaming.transport == "draft" + class TestStreamingModeAlias: """``streaming: {mode: ...}`` is an alias that also implies ``enabled``. @@ -105,10 +117,10 @@ class TestStreamingYamlBooleanQuirk: assert sc.transport == "auto" - def test_loader_normalizes_bare_yaml_off(self): + def test_loader_normalizes_bare_yaml_off(self, load_yaml): """End-to-end through load_gateway_config(): unquoted ``mode: off`` (a YAML boolean) must keep streaming disabled.""" - cfg = _load_with_yaml_dict({"streaming": {"mode": False}}) + cfg = load_yaml("streaming: {mode: off}") assert cfg.streaming.enabled is False assert cfg.streaming.transport == "off" From 4f3c4be7cac34978fc3015a6288a81c14901d118 Mon Sep 17 00:00:00 2001 From: Victor Kyriazakos Date: Wed, 9 Sep 2026 12:18:57 +0000 Subject: [PATCH 05/13] fix(config): reuse unchanged legacy gateway reads --- gateway/config_loader.py | 39 ++++-- .../gateway/relay/test_legacy_config_cache.py | 125 ++++++++++++++++++ 2 files changed, 151 insertions(+), 13 deletions(-) create mode 100644 tests/gateway/relay/test_legacy_config_cache.py diff --git a/gateway/config_loader.py b/gateway/config_loader.py index a5f147b9f0..f39ea1b78f 100644 --- a/gateway/config_loader.py +++ b/gateway/config_loader.py @@ -7,6 +7,8 @@ silently replaced by the nested one. Both overwrite whatever legacy gateway.json """ import contextlib +import copy +from functools import lru_cache import json import logging import os @@ -20,28 +22,39 @@ logger = logging.getLogger("gateway.config") def load_legacy_gateway_json(home: Path) -> Any: - """Legacy ``gateway.json`` base layer (config.yaml keys always win). Malformed → ``{}`` + warning.""" + """Legacy base layer; cache unchanged files, never merged policy or failed reads. + + Return a private copy because platform merging mutates this layer. File identity + and ctime also invalidate atomic replacements and same-size timestamp-preserving edits. + """ path = home / "gateway.json" if not path.exists(): return {} try: - with open(path, "r", encoding="utf-8") as f: - data = json.load(f) or {} - # Relay accepts a legacy opt-out as authoritative, just like YAML. - # Preserve that intent through credential activation and the exclusive - # native-adapter sweep, even when config.yaml is missing. Other legacy - # platforms retain their existing env-driven enablement semantics. - platforms = data.get("platforms") if isinstance(data, dict) else None - relay = platforms.get("relay") if isinstance(platforms, dict) else None - if isinstance(relay, dict) and "enabled" in relay: - _dict_slot(relay, "extra")["_enabled_explicit"] = True - logger.info("Loaded legacy %s — consider moving settings to config.yaml", path) - return data + st = path.stat() + version = (st.st_mtime_ns, st.st_size, st.st_ctime_ns, st.st_dev, st.st_ino) + return copy.deepcopy(_read_legacy_gateway_json(path.absolute(), version)) except Exception as e: logger.warning("Failed to load %s: %s", path, e) return {} +@lru_cache(maxsize=32) +def _read_legacy_gateway_json(path: Path, version: tuple) -> Any: + with open(path, "r", encoding="utf-8") as f: + data = json.load(f) or {} + # Relay accepts a legacy opt-out as authoritative, just like YAML. + # Preserve that intent through credential activation and the exclusive + # native-adapter sweep, even when config.yaml is missing. Other legacy + # platforms retain their existing env-driven enablement semantics. + platforms = data.get("platforms") if isinstance(data, dict) else None + relay = platforms.get("relay") if isinstance(platforms, dict) else None + if isinstance(relay, dict) and "enabled" in relay: + _dict_slot(relay, "extra")["_enabled_explicit"] = True + logger.info("Loaded legacy %s — consider moving settings to config.yaml", path) + return data + + # --- top-level key bridging ---------------------------------------------------- # # Top-level settings are also accepted nested under ``gateway:`` (what ``hermes config set diff --git a/tests/gateway/relay/test_legacy_config_cache.py b/tests/gateway/relay/test_legacy_config_cache.py new file mode 100644 index 0000000000..4e44462219 --- /dev/null +++ b/tests/gateway/relay/test_legacy_config_cache.py @@ -0,0 +1,125 @@ +"""Legacy disk caching must never become a cached relay policy decision.""" +import builtins +import json +import logging +import os +from pathlib import Path + +import pytest + +from gateway.config_loader import load_legacy_gateway_json +from gateway.relay import relay_explicitly_disabled +from hermes_constants import reset_hermes_home_override, set_hermes_home_override + + +def test_legacy_reads_are_reused_without_stale_policy(tmp_path, monkeypatch, caplog): + home = tmp_path / "primary" + other = tmp_path / "secondary" + managed = tmp_path / "managed" + for directory in (home, other, managed): + directory.mkdir() + monkeypatch.setenv("HERMES_HOME", str(home)) + monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) + legacy = home / "gateway.json" + disabled = json.dumps({"platforms": {"relay": {"enabled": False}}}) + enabled = json.dumps({"platforms": {"relay": {"enabled": True}}}) + actual_open = builtins.open + opens = [] + + def count_open(file, *args, **kwargs): + if Path(file).name == "gateway.json": + opens.append(Path(file)) + return actual_open(file, *args, **kwargs) + + monkeypatch.setattr(builtins, "open", count_open) + caplog.set_level(logging.INFO, logger="gateway.config") + assert not relay_explicitly_disabled() # An absent file must not be cached. + legacy.write_text(disabled, encoding="utf-8") + for _ in range(10): + assert relay_explicitly_disabled() + assert opens == [legacy] + assert len([r for r in caplog.records if "Loaded legacy" in r.message]) == 1 + + # Both the marker-bearing parse and nested data belong to each caller. + loaded = load_legacy_gateway_json(home) + loaded["platforms"]["relay"]["enabled"] = True + loaded["platforms"]["relay"]["extra"]["_enabled_explicit"] = False + assert relay_explicitly_disabled() + assert load_legacy_gateway_json(home)["platforms"]["relay"]["extra"]["_enabled_explicit"] + + (other / "gateway.json").write_text(enabled, encoding="utf-8") + token = set_hermes_home_override(other) + try: + assert not relay_explicitly_disabled() + finally: + reset_hermes_home_override(token) + assert relay_explicitly_disabled() + assert opens == [legacy, other / "gateway.json"] + + # User and managed policy are recomposed even on a legacy cache hit. + user = home / "config.yaml" + user.write_text("platforms:\n relay:\n enabled: true\n", encoding="utf-8") + assert not relay_explicitly_disabled() + overlay = managed / "config.yaml" + overlay.write_text("platforms:\n relay:\n enabled: ${CACHE_TEST_RELAY}\n", encoding="utf-8") + monkeypatch.setenv("CACHE_TEST_RELAY", "false") + assert relay_explicitly_disabled() + monkeypatch.setenv("CACHE_TEST_RELAY", "true") + assert not relay_explicitly_disabled() + overlay.write_text("platforms:\n relay:\n enabled: false\n", encoding="utf-8") + assert relay_explicitly_disabled() + overlay.unlink() + assert not relay_explicitly_disabled() + user.unlink() + assert relay_explicitly_disabled() + assert opens == [legacy, other / "gateway.json"] + + legacy.write_text(enabled, encoding="utf-8") + assert not relay_explicitly_disabled() + # Atomic replacement must invalidate even with equal mtime and byte length. + replacement = home / "replacement.json" + replacement.write_text(disabled, encoding="utf-8") + replacement.replace(legacy) + assert relay_explicitly_disabled() + stat = legacy.stat() + replacement.write_text(enabled + " ", encoding="utf-8") + os.utime(replacement, ns=(stat.st_atime_ns, stat.st_mtime_ns)) + assert replacement.stat().st_size == stat.st_size + replacement.replace(legacy) + assert not relay_explicitly_disabled() + legacy.unlink() + assert not relay_explicitly_disabled() + legacy.write_text(disabled, encoding="utf-8") + assert relay_explicitly_disabled() + + +@pytest.mark.parametrize("invalid", ["malformed", "unreadable"]) +def test_failed_legacy_reads_warn_and_recover(tmp_path, monkeypatch, caplog, invalid): + legacy = tmp_path / "gateway.json" + valid = json.dumps({"platforms": {"relay": {"enabled": False}}}) + legacy.write_text(valid, encoding="utf-8") + assert load_legacy_gateway_json(tmp_path)["platforms"]["relay"]["enabled"] is False + caplog.set_level(logging.WARNING, logger="gateway.config") + actual_open = builtins.open + unreadable = invalid == "unreadable" + attempts = [] + + def read(file, *args, **kwargs): + if Path(file) == legacy: + attempts.append(file) + if unreadable: + raise PermissionError("synthetic unreadable legacy file") + return actual_open(file, *args, **kwargs) + + monkeypatch.setattr(builtins, "open", read) + legacy.write_text("{" if invalid == "malformed" else valid + " ", encoding="utf-8") + for _ in range(2): + assert load_legacy_gateway_json(tmp_path) == {} + assert len(attempts) == 2 + assert len([r for r in caplog.records if "Failed to load" in r.message]) == 2 + unreadable = False + # A different recovered value proves we did not resurrect the old parse. + legacy.write_text(json.dumps({"platforms": {"relay": {"enabled": True}}}), encoding="utf-8") + assert load_legacy_gateway_json(tmp_path)["platforms"]["relay"]["enabled"] is True + assert load_legacy_gateway_json(tmp_path)["platforms"]["relay"]["enabled"] is True + assert len(attempts) == 3 From c15e1e94c115ecf7428e973a219e5bda22b17a64 Mon Sep 17 00:00:00 2001 From: Victor Kyriazakos Date: Wed, 9 Sep 2026 12:20:49 +0000 Subject: [PATCH 06/13] fix(relay): log terminal config opt-out on websocket dial --- gateway/relay/ws_transport.py | 1 + tests/gateway/relay/test_explicit_disable.py | 19 +++++++++++++++---- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/gateway/relay/ws_transport.py b/gateway/relay/ws_transport.py index 55ea2bcf5c..142d761668 100644 --- a/gateway/relay/ws_transport.py +++ b/gateway/relay/ws_transport.py @@ -424,6 +424,7 @@ class WebSocketRelayTransport: from gateway.relay import relay_explicitly_disabled if relay_explicitly_disabled(): + logger.info("relay ws disabled by config; not connecting or retrying") raise _RelayDisabled("Relay explicitly disabled in config") self._descriptor_ready = asyncio.get_running_loop().create_future() self._dial_generation += 1 diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py index 55019dc058..dbb2be4d6c 100644 --- a/tests/gateway/relay/test_explicit_disable.py +++ b/tests/gateway/relay/test_explicit_disable.py @@ -5,7 +5,9 @@ I/O and unrelated gateway services are replaced. No connector is contacted. """ from types import SimpleNamespace from unittest.mock import AsyncMock, Mock +import asyncio import json +import logging import os import pytest @@ -294,7 +296,7 @@ def test_managed_layer_agrees_with_native_config(profile, monkeypatch, user_yaml "transport-connect", "transport-reconnect", "fresh-token", "media-hook", "cached-media-hook", "upload", "download", "public-download"]) @pytest.mark.parametrize("spelling", ["top", "nested", "normalized", "legacy-json", "yaml-wins", "gateway-relay", "top-relay", "managed-disable", "sibling-keeps-disable"]) -async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, monkeypatch, entry, spelling): +async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, monkeypatch, caplog, entry, spelling): block = {"enabled": "false" if spelling == "normalized" else False} cfg = {"gateway": {"relay_url": URL}} if spelling == "nested": @@ -355,18 +357,27 @@ async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, mon transport.connect.assert_not_awaited() transport.set_inbound_handler.assert_not_called() elif entry in {"transport-connect", "transport-reconnect", "fresh-token"}: - ws = WebSocketRelayTransport(URL, "slack", "bot", reconnect_backoff_s=0) + caplog.set_level(logging.INFO, logger="gateway.relay.ws_transport") + ws = WebSocketRelayTransport(URL, "slack", "bot", reconnect_backoff_s=0, + gateway_id="shared-gateway", upgrade_secret="a" * 64) dial = AsyncMock() + mint = Mock(side_effect=AssertionError("disabled relay minted a token")) + monkeypatch.setattr("gateway.relay.auth.make_upgrade_token", mint) monkeypatch.setattr("gateway.relay.ws_transport.websockets.connect", dial) if entry == "transport-connect": assert await ws.connect() is False elif entry == "fresh-token": - await ws._redial_with_fresh_token() + await asyncio.wait_for(ws._redial_with_fresh_token(), timeout=2) else: - await ws._reconnect_loop() + await asyncio.wait_for(ws._reconnect_loop(), timeout=2) dial.assert_not_awaited() + mint.assert_not_called() assert ws._reader is None assert ws._supervisor is None + assert ws._dial_generation == 0 + assert [(r.levelno, r.message) for r in caplog.records + if r.name == "gateway.relay.ws_transport"] == [ + (logging.INFO, "relay ws disabled by config; not connecting or retrying")] elif entry in {"media-hook", "cached-media-hook"}: if entry == "cached-media-hook": adapter._media_client = media From 5746b5bae6445f485c96b5d4d7d31c5bbca2179a Mon Sep 17 00:00:00 2001 From: Ben Barclay Date: Fri, 11 Sep 2026 10:25:38 +1000 Subject: [PATCH 07/13] fix(relay): veto the disable at the activation boundary only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every relay object (adapter, media client, WS transport) is constructed inside the registry factory that register_relay_adapter() installs, and that call plus self_provision_relay()/send_relay_policy() all resolve through relay_url(). So the opt-out has three reachable boundaries: relay_url(), relay_fronted_platforms() (env-sourced, standalone cron) and the force=/url= bypass in register_relay_adapter(). The guards on RelayAdapter.connect, _get_media_client, RelayMediaClient.enabled/download and every WS dial/redial were unreachable unless config flipped on a RUNNING gateway — which the docs in this PR say is unsupported. Half-honoring that flip is worse than not honoring it: inbound kept flowing over the open socket while media downloads silently returned None and the next redial terminated. Drop those five guards, the _RelayDisabled terminal exception they needed, and the legacy-JSON lru_cache that existed only to make a full config merge affordable on the per-message path. The activation-time predicate runs a handful of times per boot; the shared raw-config and managed-scope readers already cache on mtime. --- gateway/config_loader.py | 36 ++--- gateway/relay/adapter.py | 9 -- gateway/relay/media.py | 8 +- gateway/relay/ws_transport.py | 18 +-- tests/gateway/relay/test_explicit_disable.py | 54 +------- .../gateway/relay/test_legacy_config_cache.py | 125 ------------------ 6 files changed, 16 insertions(+), 234 deletions(-) delete mode 100644 tests/gateway/relay/test_legacy_config_cache.py diff --git a/gateway/config_loader.py b/gateway/config_loader.py index f39ea1b78f..a985c841b1 100644 --- a/gateway/config_loader.py +++ b/gateway/config_loader.py @@ -7,8 +7,6 @@ silently replaced by the nested one. Both overwrite whatever legacy gateway.json """ import contextlib -import copy -from functools import lru_cache import json import logging import os @@ -22,39 +20,25 @@ logger = logging.getLogger("gateway.config") def load_legacy_gateway_json(home: Path) -> Any: - """Legacy base layer; cache unchanged files, never merged policy or failed reads. - - Return a private copy because platform merging mutates this layer. File identity - and ctime also invalidate atomic replacements and same-size timestamp-preserving edits. - """ + """Legacy ``gateway.json`` base layer (config.yaml keys always win). Malformed → ``{}`` + warning.""" path = home / "gateway.json" if not path.exists(): return {} try: - st = path.stat() - version = (st.st_mtime_ns, st.st_size, st.st_ctime_ns, st.st_dev, st.st_ino) - return copy.deepcopy(_read_legacy_gateway_json(path.absolute(), version)) + with open(path, "r", encoding="utf-8") as f: + data = json.load(f) or {} + # Relay accepts a legacy opt-out as authoritative, just like YAML. + platforms = data.get("platforms") if isinstance(data, dict) else None + relay = platforms.get("relay") if isinstance(platforms, dict) else None + if isinstance(relay, dict) and "enabled" in relay: + _dict_slot(relay, "extra")["_enabled_explicit"] = True + logger.info("Loaded legacy %s — consider moving settings to config.yaml", path) + return data except Exception as e: logger.warning("Failed to load %s: %s", path, e) return {} -@lru_cache(maxsize=32) -def _read_legacy_gateway_json(path: Path, version: tuple) -> Any: - with open(path, "r", encoding="utf-8") as f: - data = json.load(f) or {} - # Relay accepts a legacy opt-out as authoritative, just like YAML. - # Preserve that intent through credential activation and the exclusive - # native-adapter sweep, even when config.yaml is missing. Other legacy - # platforms retain their existing env-driven enablement semantics. - platforms = data.get("platforms") if isinstance(data, dict) else None - relay = platforms.get("relay") if isinstance(platforms, dict) else None - if isinstance(relay, dict) and "enabled" in relay: - _dict_slot(relay, "extra")["_enabled_explicit"] = True - logger.info("Loaded legacy %s — consider moving settings to config.yaml", path) - return data - - # --- top-level key bridging ---------------------------------------------------- # # Top-level settings are also accepted nested under ``gateway:`` (what ``hermes config set diff --git a/gateway/relay/adapter.py b/gateway/relay/adapter.py index b2ac6d753a..111959bb32 100644 --- a/gateway/relay/adapter.py +++ b/gateway/relay/adapter.py @@ -738,11 +738,6 @@ class RelayAdapter(BasePlatformAdapter): # ── abstract methods (delegated to the transport) ──────────────────── async def connect(self, *, is_reconnect: bool = False) -> bool: - from gateway.relay import relay_explicitly_disabled - - if relay_explicitly_disabled(): - self._set_fatal_error("relay_disabled", "Relay explicitly disabled in config", retryable=False) - return False # ``is_reconnect`` is part of the BasePlatformAdapter.connect contract (the # reconnect watcher passes it; refusing the kwarg would break recovery). # Relay IGNORES it: messages buffered during a gap live in the CONNECTOR's @@ -1702,10 +1697,6 @@ class RelayAdapter(BasePlatformAdapter): """Lazily build the authenticated /relay/media client from the SAME dial URL and per-gateway creds the WS uses; None when unavailable (media lanes then degrade to their pre-media fallbacks).""" - from gateway.relay import relay_explicitly_disabled - - if relay_explicitly_disabled(): - return None if self._media_client is not None: return self._media_client try: diff --git a/gateway/relay/media.py b/gateway/relay/media.py index 0045424f14..4b957f4165 100644 --- a/gateway/relay/media.py +++ b/gateway/relay/media.py @@ -60,9 +60,7 @@ class RelayMediaClient: @property def enabled(self) -> bool: """True when the client can authenticate (per-gateway creds present).""" - from gateway.relay import relay_explicitly_disabled - - return bool(self._base_url and self._gateway_id and self._secret) and not relay_explicitly_disabled() + return bool(self._base_url and self._gateway_id and self._secret) def _bearer(self) -> str: return make_upgrade_token(self._gateway_id, self._secret) @@ -117,9 +115,7 @@ class RelayMediaClient: The bearer is presented only for connector re-host URLs; public URLs (e.g. a Discord CDN pass-through) are fetched without it. """ - from gateway.relay import relay_explicitly_disabled - - if not url or relay_explicitly_disabled(): + if not url: return None needs_auth = self.is_relay_media_url(url) if needs_auth and not self.enabled: diff --git a/gateway/relay/ws_transport.py b/gateway/relay/ws_transport.py index 142d761668..f6bdaa97d5 100644 --- a/gateway/relay/ws_transport.py +++ b/gateway/relay/ws_transport.py @@ -305,10 +305,6 @@ async def _await_bounded(aw: Awaitable[Any]) -> None: REDIAL_HOLD_MAX_S = 60.0 -class _RelayDisabled(RuntimeError): - """Local profile opt-out is terminal, not a transient dial failure.""" - - class WebSocketRelayTransport: """RelayTransport over a WebSocket connection the gateway dials to the connector.""" @@ -412,20 +408,12 @@ class WebSocketRelayTransport: # ── lifecycle ──────────────────────────────────────────────────────── async def connect(self) -> bool: - try: - await self._dial_and_start() - except _RelayDisabled: - return False + await self._dial_and_start() return True async def _dial_and_start(self) -> None: """Open the socket, start the reader, send hello(s). Used by connect() and by the reconnect supervisor / fresh-token retry on a re-dial.""" - from gateway.relay import relay_explicitly_disabled - - if relay_explicitly_disabled(): - logger.info("relay ws disabled by config; not connecting or retrying") - raise _RelayDisabled("Relay explicitly disabled in config") self._descriptor_ready = asyncio.get_running_loop().create_future() self._dial_generation += 1 # Fresh handshake generation: a reconnected connector re-sends one @@ -835,8 +823,6 @@ class WebSocketRelayTransport: try: await self._dial_and_start() logger.info("relay ws re-dialed with a fresh upgrade token after 4401") - except _RelayDisabled: - return except asyncio.CancelledError: raise except Exception as exc: # noqa: BLE001 - fall back to the backoff supervisor @@ -886,8 +872,6 @@ class WebSocketRelayTransport: await self._dial_and_start() logger.info("relay ws reconnected") return - except _RelayDisabled: - return except Exception as exc: # noqa: BLE001 - keep retrying on dial failure if self._latch_if_fresh_token_refused(exc): return diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py index dbb2be4d6c..b20f677770 100644 --- a/tests/gateway/relay/test_explicit_disable.py +++ b/tests/gateway/relay/test_explicit_disable.py @@ -5,20 +5,17 @@ I/O and unrelated gateway services are replaced. No connector is contacted. """ from types import SimpleNamespace from unittest.mock import AsyncMock, Mock -import asyncio import json -import logging import os import pytest import yaml import gateway.relay as relay -from gateway.config import Platform, PlatformConfig, load_gateway_config +from gateway.config import Platform, load_gateway_config from gateway.platform_registry import platform_registry from gateway.relay.adapter import RelayAdapter from gateway.relay.descriptor import CapabilityDescriptor, CONTRACT_VERSION -from gateway.relay.media import RelayMediaClient from gateway.relay.ws_transport import WebSocketRelayTransport from gateway.run_startup import GatewayStartupMixin @@ -291,12 +288,9 @@ def test_managed_layer_agrees_with_native_config(profile, monkeypatch, user_yaml @pytest.mark.asyncio -@pytest.mark.parametrize("entry", ["url", "provision", "policy", "registration", "forced-registration", - "fronted", "adapter-connect", "adapter-reconnect", - "transport-connect", "transport-reconnect", "fresh-token", "media-hook", - "cached-media-hook", "upload", "download", "public-download"]) +@pytest.mark.parametrize("entry", ["url", "provision", "policy", "registration", "forced-registration", "fronted"]) @pytest.mark.parametrize("spelling", ["top", "nested", "normalized", "legacy-json", "yaml-wins", "gateway-relay", "top-relay", "managed-disable", "sibling-keeps-disable"]) -async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, monkeypatch, caplog, entry, spelling): +async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, monkeypatch, entry, spelling): block = {"enabled": "false" if spelling == "normalized" else False} cfg = {"gateway": {"relay_url": URL}} if spelling == "nested": @@ -330,13 +324,6 @@ async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, mon monkeypatch.setattr("urllib.request.urlopen", http) provision = Mock(return_value={"secret": "b" * 64, "gatewayId": "replaced"}) monkeypatch.setattr(relay, "_post_provision", provision) - transport = SimpleNamespace(connect=AsyncMock(return_value=True), - handshake=AsyncMock(return_value=descriptor()), - set_inbound_handler=Mock()) - adapter = RelayAdapter(PlatformConfig(enabled=True), descriptor(), transport=transport) - media = RelayMediaClient("https://connector.example", "shared-gateway", "a" * 64) - file = profile / "attachment.txt" - file.write_text("attachment", encoding="utf-8") if entry == "url": assert relay.relay_url() is None @@ -352,41 +339,6 @@ async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, mon assert not platform_registry.is_registered("relay") elif entry == "fronted": assert relay.relay_fronted_platforms() == set() - elif entry in {"adapter-connect", "adapter-reconnect"}: - assert await adapter.connect(is_reconnect=entry == "adapter-reconnect") is False - transport.connect.assert_not_awaited() - transport.set_inbound_handler.assert_not_called() - elif entry in {"transport-connect", "transport-reconnect", "fresh-token"}: - caplog.set_level(logging.INFO, logger="gateway.relay.ws_transport") - ws = WebSocketRelayTransport(URL, "slack", "bot", reconnect_backoff_s=0, - gateway_id="shared-gateway", upgrade_secret="a" * 64) - dial = AsyncMock() - mint = Mock(side_effect=AssertionError("disabled relay minted a token")) - monkeypatch.setattr("gateway.relay.auth.make_upgrade_token", mint) - monkeypatch.setattr("gateway.relay.ws_transport.websockets.connect", dial) - if entry == "transport-connect": - assert await ws.connect() is False - elif entry == "fresh-token": - await asyncio.wait_for(ws._redial_with_fresh_token(), timeout=2) - else: - await asyncio.wait_for(ws._reconnect_loop(), timeout=2) - dial.assert_not_awaited() - mint.assert_not_called() - assert ws._reader is None - assert ws._supervisor is None - assert ws._dial_generation == 0 - assert [(r.levelno, r.message) for r in caplog.records - if r.name == "gateway.relay.ws_transport"] == [ - (logging.INFO, "relay ws disabled by config; not connecting or retrying")] - elif entry in {"media-hook", "cached-media-hook"}: - if entry == "cached-media-hook": - adapter._media_client = media - assert adapter._get_media_client() is None - elif entry == "upload": - assert await media.upload(str(file)) is None - else: - url = "https://connector.example/relay/media/id" if entry == "download" else "https://cdn.example/file" - assert await media.download(url) is None http.assert_not_called() provision.assert_not_called() diff --git a/tests/gateway/relay/test_legacy_config_cache.py b/tests/gateway/relay/test_legacy_config_cache.py deleted file mode 100644 index 4e44462219..0000000000 --- a/tests/gateway/relay/test_legacy_config_cache.py +++ /dev/null @@ -1,125 +0,0 @@ -"""Legacy disk caching must never become a cached relay policy decision.""" -import builtins -import json -import logging -import os -from pathlib import Path - -import pytest - -from gateway.config_loader import load_legacy_gateway_json -from gateway.relay import relay_explicitly_disabled -from hermes_constants import reset_hermes_home_override, set_hermes_home_override - - -def test_legacy_reads_are_reused_without_stale_policy(tmp_path, monkeypatch, caplog): - home = tmp_path / "primary" - other = tmp_path / "secondary" - managed = tmp_path / "managed" - for directory in (home, other, managed): - directory.mkdir() - monkeypatch.setenv("HERMES_HOME", str(home)) - monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) - legacy = home / "gateway.json" - disabled = json.dumps({"platforms": {"relay": {"enabled": False}}}) - enabled = json.dumps({"platforms": {"relay": {"enabled": True}}}) - actual_open = builtins.open - opens = [] - - def count_open(file, *args, **kwargs): - if Path(file).name == "gateway.json": - opens.append(Path(file)) - return actual_open(file, *args, **kwargs) - - monkeypatch.setattr(builtins, "open", count_open) - caplog.set_level(logging.INFO, logger="gateway.config") - assert not relay_explicitly_disabled() # An absent file must not be cached. - legacy.write_text(disabled, encoding="utf-8") - for _ in range(10): - assert relay_explicitly_disabled() - assert opens == [legacy] - assert len([r for r in caplog.records if "Loaded legacy" in r.message]) == 1 - - # Both the marker-bearing parse and nested data belong to each caller. - loaded = load_legacy_gateway_json(home) - loaded["platforms"]["relay"]["enabled"] = True - loaded["platforms"]["relay"]["extra"]["_enabled_explicit"] = False - assert relay_explicitly_disabled() - assert load_legacy_gateway_json(home)["platforms"]["relay"]["extra"]["_enabled_explicit"] - - (other / "gateway.json").write_text(enabled, encoding="utf-8") - token = set_hermes_home_override(other) - try: - assert not relay_explicitly_disabled() - finally: - reset_hermes_home_override(token) - assert relay_explicitly_disabled() - assert opens == [legacy, other / "gateway.json"] - - # User and managed policy are recomposed even on a legacy cache hit. - user = home / "config.yaml" - user.write_text("platforms:\n relay:\n enabled: true\n", encoding="utf-8") - assert not relay_explicitly_disabled() - overlay = managed / "config.yaml" - overlay.write_text("platforms:\n relay:\n enabled: ${CACHE_TEST_RELAY}\n", encoding="utf-8") - monkeypatch.setenv("CACHE_TEST_RELAY", "false") - assert relay_explicitly_disabled() - monkeypatch.setenv("CACHE_TEST_RELAY", "true") - assert not relay_explicitly_disabled() - overlay.write_text("platforms:\n relay:\n enabled: false\n", encoding="utf-8") - assert relay_explicitly_disabled() - overlay.unlink() - assert not relay_explicitly_disabled() - user.unlink() - assert relay_explicitly_disabled() - assert opens == [legacy, other / "gateway.json"] - - legacy.write_text(enabled, encoding="utf-8") - assert not relay_explicitly_disabled() - # Atomic replacement must invalidate even with equal mtime and byte length. - replacement = home / "replacement.json" - replacement.write_text(disabled, encoding="utf-8") - replacement.replace(legacy) - assert relay_explicitly_disabled() - stat = legacy.stat() - replacement.write_text(enabled + " ", encoding="utf-8") - os.utime(replacement, ns=(stat.st_atime_ns, stat.st_mtime_ns)) - assert replacement.stat().st_size == stat.st_size - replacement.replace(legacy) - assert not relay_explicitly_disabled() - legacy.unlink() - assert not relay_explicitly_disabled() - legacy.write_text(disabled, encoding="utf-8") - assert relay_explicitly_disabled() - - -@pytest.mark.parametrize("invalid", ["malformed", "unreadable"]) -def test_failed_legacy_reads_warn_and_recover(tmp_path, monkeypatch, caplog, invalid): - legacy = tmp_path / "gateway.json" - valid = json.dumps({"platforms": {"relay": {"enabled": False}}}) - legacy.write_text(valid, encoding="utf-8") - assert load_legacy_gateway_json(tmp_path)["platforms"]["relay"]["enabled"] is False - caplog.set_level(logging.WARNING, logger="gateway.config") - actual_open = builtins.open - unreadable = invalid == "unreadable" - attempts = [] - - def read(file, *args, **kwargs): - if Path(file) == legacy: - attempts.append(file) - if unreadable: - raise PermissionError("synthetic unreadable legacy file") - return actual_open(file, *args, **kwargs) - - monkeypatch.setattr(builtins, "open", read) - legacy.write_text("{" if invalid == "malformed" else valid + " ", encoding="utf-8") - for _ in range(2): - assert load_legacy_gateway_json(tmp_path) == {} - assert len(attempts) == 2 - assert len([r for r in caplog.records if "Failed to load" in r.message]) == 2 - unreadable = False - # A different recovered value proves we did not resurrect the old parse. - legacy.write_text(json.dumps({"platforms": {"relay": {"enabled": True}}}), encoding="utf-8") - assert load_legacy_gateway_json(tmp_path)["platforms"]["relay"]["enabled"] is True - assert load_legacy_gateway_json(tmp_path)["platforms"]["relay"]["enabled"] is True - assert len(attempts) == 3 From 337d69856f4fa5043fdfab035f2c923a6240da60 Mon Sep 17 00:00:00 2001 From: Ben Barclay Date: Fri, 11 Sep 2026 10:27:14 +1000 Subject: [PATCH 08/13] fix(relay): legacy gateway.json opt-out is advisory, like every platform MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The loader stamps _enabled_explicit only from YAML blocks; a gateway.json `enabled: false` is re-enabled by env presence for slack, telegram and everyone else. Tagging the marker for platforms.relay alone in the legacy reader made relay the one platform whose gateway.json verdict beat the env — a per-platform pin nobody would find later. If legacy opt-outs should become authoritative, that is one rule for all platforms in its own PR. relay_explicitly_disabled() now reads the marker the loader itself sets instead of re-deriving the verdict from 'enabled' in block, so the standalone predicate and load_gateway_config() cannot disagree. --- gateway/config_loader.py | 5 --- gateway/relay/__init__.py | 37 +++++++------------- tests/gateway/relay/test_cold_opt_out.py | 6 ++-- tests/gateway/relay/test_explicit_disable.py | 26 ++++---------- 4 files changed, 22 insertions(+), 52 deletions(-) diff --git a/gateway/config_loader.py b/gateway/config_loader.py index a985c841b1..052d3f2fa7 100644 --- a/gateway/config_loader.py +++ b/gateway/config_loader.py @@ -27,11 +27,6 @@ def load_legacy_gateway_json(home: Path) -> Any: try: with open(path, "r", encoding="utf-8") as f: data = json.load(f) or {} - # Relay accepts a legacy opt-out as authoritative, just like YAML. - platforms = data.get("platforms") if isinstance(data, dict) else None - relay = platforms.get("relay") if isinstance(platforms, dict) else None - if isinstance(relay, dict) and "enabled" in relay: - _dict_slot(relay, "extra")["_enabled_explicit"] = True logger.info("Loaded legacy %s — consider moving settings to config.yaml", path) return data except Exception as e: diff --git a/gateway/relay/__init__.py b/gateway/relay/__init__.py index f0fbfa7c7d..148715a65a 100644 --- a/gateway/relay/__init__.py +++ b/gateway/relay/__init__.py @@ -71,38 +71,27 @@ def _env_or_cfg_url(env_var: str, cfg_key: str) -> Optional[str]: def relay_explicitly_disabled() -> bool: - """The profile's normalized opt-out, before any URL/credential activation. + """``platforms.relay.enabled: false`` in the profile's YAML (user or managed). - Reuse the gateway's platform merge and boolean normalization without running - its env/plugin side effects. Absence is not a disable: URL-only deployments - predate the platform flag. The raw loader includes managed configuration. + Same merge and boolean normalization as the gateway loader, minus its env/plugin + side effects, so a standalone scheduler can ask without bootstrapping the gateway. + Mirrors the loader's ``_enabled_explicit`` rule: only a YAML ``enabled`` key is + authoritative — a legacy ``gateway.json`` block is advisory for relay exactly as it + is for every other platform, and an absent key keeps URL-only activation. """ from gateway.config import Platform, PlatformConfig - from gateway.config_loader import ( - bridge_platform_shared_keys, load_legacy_gateway_json, merge_platform_sections, - ) - from hermes_constants import get_hermes_home + from gateway.config_loader import bridge_platform_shared_keys, merge_platform_sections from hermes_cli.config import read_raw_config from hermes_cli.managed_scope import apply_managed_overlay - # Do not import gateway.run here: standalone routing must not bootstrap - # runtime flags, config-to-env bridges or dotenv. The shared cached reader - # resolves the context-local home; the same managed overlay is used by the - # runtime loader, without introducing CLI defaults into platform precedence. cfg = apply_managed_overlay(read_raw_config()) - data = load_legacy_gateway_json(get_hermes_home()) - platforms = merge_platform_sections(cfg, cfg.get("gateway"), data) - gateway = cfg.get("gateway") or {} - bridge_platform_shared_keys( - cfg, gateway.get("platforms") if isinstance(gateway, dict) else None, - data, platforms, [Platform.RELAY], - ) + gateway = cfg.get("gateway") if isinstance(cfg.get("gateway"), dict) else {} + platforms = merge_platform_sections(cfg, gateway, {}) + bridge_platform_shared_keys(cfg, gateway.get("platforms"), {}, platforms, [Platform.RELAY]) block = platforms.get("relay") - return ( - isinstance(block, dict) - and "enabled" in block - and not PlatformConfig.from_dict(block).enabled - ) + if not isinstance(block, dict) or not block.get("extra", {}).get("_enabled_explicit"): + return False + return not PlatformConfig.from_dict(block).enabled def relay_url() -> Optional[str]: diff --git a/tests/gateway/relay/test_cold_opt_out.py b/tests/gateway/relay/test_cold_opt_out.py index b113739fa5..ac6705e5db 100644 --- a/tests/gateway/relay/test_cold_opt_out.py +++ b/tests/gateway/relay/test_cold_opt_out.py @@ -10,7 +10,7 @@ import pytest import yaml -@pytest.mark.parametrize("case", ["native", "url-only", "disabled", "managed", "managed-only", "scoped", "scoped-json"]) +@pytest.mark.parametrize("case", ["native", "url-only", "disabled", "managed", "managed-only", "scoped"]) def test_cold_fronted_platforms_is_read_only(tmp_path, case): home = tmp_path / "primary" home.mkdir() @@ -27,8 +27,6 @@ def test_cold_fronted_platforms_is_read_only(tmp_path, case): (managed / "config.yaml").write_text("platforms:\n relay:\n enabled: false\n") if case == "scoped": (scoped / "config.yaml").write_text("platforms:\n relay:\n enabled: false\n") - elif case == "scoped-json": - (scoped / "gateway.json").write_text(json.dumps({"platforms": {"relay": {"enabled": False}}})) for root in (home, scoped): (root / ".env").write_text("GATEWAY_RELAY_SECRET=dotenv-only-test-secret\n") # Allowlist only: never inherit live credentials, profile selectors, or @@ -45,7 +43,7 @@ def test_cold_fronted_platforms_is_read_only(tmp_path, case): code = textwrap.dedent(""" import json, os, sys from hermes_constants import set_hermes_home_override - if sys.argv[1].startswith("scoped"): + if sys.argv[1] == "scoped": set_hermes_home_override(sys.argv[2]) before = dict(os.environ) assert "gateway.run" not in sys.modules diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py index b20f677770..de5c04485a 100644 --- a/tests/gateway/relay/test_explicit_disable.py +++ b/tests/gateway/relay/test_explicit_disable.py @@ -64,10 +64,7 @@ def configure(home, state, source, monkeypatch): monkeypatch.setenv("GATEWAY_RELAY_URL", URL) assert not (home / "config.yaml").exists() return - if source == "legacy-json": - (home / "gateway.json").write_text(json.dumps({"platforms": cfg.pop("platforms")})) - monkeypatch.setenv("GATEWAY_RELAY_URL", URL) - elif source == "env": + if source == "env": monkeypatch.setenv("GATEWAY_RELAY_URL", URL) elif source == "managed": managed = home / "managed" @@ -200,17 +197,9 @@ async def test_production_startup_respects_profile_opt_out(profile, monkeypatch, assert "relay-fronted" in error -@pytest.mark.asyncio -@pytest.mark.parametrize("pinned", [False, True], ids=["unprovisioned", "inherited-secret"]) -async def test_legacy_json_disable_preserves_startup_and_native_delivery(profile, monkeypatch, pinned): - await test_production_startup_respects_profile_opt_out( - profile, monkeypatch, False, "legacy-json", pinned, - ) - - @pytest.mark.parametrize("yaml_state", ["absent", "empty", "sibling", "enabled"]) @pytest.mark.parametrize("disabled", [False, "false"]) -def test_legacy_json_disable_agrees_with_normalized_config(profile, monkeypatch, yaml_state, disabled): +def test_legacy_json_disable_is_advisory_like_other_platforms(profile, monkeypatch, yaml_state, disabled): (profile / "gateway.json").write_text(json.dumps({"platforms": { "relay": {"enabled": disabled}, "slack": {"enabled": True, "token": "native-test-token"}, @@ -225,11 +214,12 @@ def test_legacy_json_disable_agrees_with_normalized_config(profile, monkeypatch, (profile / "config.yaml").write_text(yaml.safe_dump(cfg)) monkeypatch.setenv("GATEWAY_RELAY_URL", URL) monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "native-telegram-test-token") - # Other legacy platforms keep their existing credential-driven enablement. monkeypatch.setenv("GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS", "true") config = load_gateway_config() - assert relay.relay_explicitly_disabled() is (yaml_state != "enabled") - assert config.platforms[Platform.RELAY].enabled is (yaml_state == "enabled") + # A legacy gateway.json ``enabled`` is advisory for relay exactly as it is for telegram: + # env presence (the URL / the token) re-enables both. Only YAML sets ``_enabled_explicit``. + assert relay.relay_explicitly_disabled() is False + assert config.platforms[Platform.RELAY].enabled assert config.platforms[Platform.SLACK].enabled assert config.platforms[Platform.TELEGRAM].enabled @@ -289,7 +279,7 @@ def test_managed_layer_agrees_with_native_config(profile, monkeypatch, user_yaml @pytest.mark.asyncio @pytest.mark.parametrize("entry", ["url", "provision", "policy", "registration", "forced-registration", "fronted"]) -@pytest.mark.parametrize("spelling", ["top", "nested", "normalized", "legacy-json", "yaml-wins", "gateway-relay", "top-relay", "managed-disable", "sibling-keeps-disable"]) +@pytest.mark.parametrize("spelling", ["top", "nested", "normalized", "yaml-wins", "gateway-relay", "top-relay", "managed-disable", "sibling-keeps-disable"]) async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, monkeypatch, entry, spelling): block = {"enabled": "false" if spelling == "normalized" else False} cfg = {"gateway": {"relay_url": URL}} @@ -301,8 +291,6 @@ async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, mon elif spelling == "top-relay": cfg["relay"] = block cfg["gateway"]["relay"] = {"enabled": True} - elif spelling == "legacy-json": - (profile / "gateway.json").write_text(json.dumps({"platforms": {"relay": block}})) elif spelling == "managed-disable": cfg["platforms"] = {"relay": {"enabled": True}} managed = profile / "managed" From 1d5debfa650d63deb0a01feb0c24402ad4b089b7 Mon Sep 17 00:00:00 2001 From: Ben Barclay Date: Fri, 11 Sep 2026 10:28:13 +1000 Subject: [PATCH 09/13] fix(config): apply managed overlay when the user config.yaml is absent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Narrow the PR's load_yaml_layer rewrite to the one behavior the relay fix needs: an absent user file is an empty layer, so administrator- pinned values (a managed relay opt-out among them) still reach the gateway on a host with no config.yaml. Everything else returns to the loader's existing contract. A MALFORMED user file still raises so load_gateway_config() keeps emitting its 'Failed to process config.yaml — falling back to .env / gateway.json' warning instead of silently applying the managed layer over the broken one; the loader keeps its own yaml read rather than importing the CLI's raw reader. Changing the malformed-file contract touches every platform and belongs in its own PR. --- gateway/config_loader.py | 26 +++++++++++--------- tests/gateway/relay/test_explicit_disable.py | 9 +++---- 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/gateway/config_loader.py b/gateway/config_loader.py index 052d3f2fa7..dd638e4b96 100644 --- a/gateway/config_loader.py +++ b/gateway/config_loader.py @@ -336,19 +336,21 @@ def bridge_core_env_settings(yaml_cfg: dict, platforms_data: dict) -> None: def load_yaml_layer(home: Path, gw_data: dict) -> None: - """Overlay raw user + managed YAML onto *gw_data* without introducing CLI defaults.""" - from hermes_cli.config import read_user_config_raw - from hermes_cli import managed_scope + """Overlay ``config.yaml`` + managed YAML onto *gw_data* in place. Raises on a malformed user + file (caller warns + falls back). An ABSENT user file is an empty layer, not a reason to skip + the administrator's values: a fleet host with no ``config.yaml`` must still honor them. + """ + import yaml - # Match the raw runtime/predicate readers: absent, unreadable or malformed - # user YAML is an empty layer, not a reason to skip administrator settings. - # Use the explicit home rather than a process-global path (multiplex-safe). - try: - yaml_cfg = read_user_config_raw(home / "config.yaml") - except Exception as e: - logger.warning("Failed to read %s; applying managed config over an empty user layer: %s", - home / "config.yaml", e) - yaml_cfg = {} + config_yaml_path = home / "config.yaml" + yaml_cfg: dict = {} + if config_yaml_path.exists(): + with open(config_yaml_path, encoding="utf-8") as f: + yaml_cfg = yaml.safe_load(f) or {} + + # Managed scope: overlay administrator-pinned values (this loader bypasses + # hermes_cli.config.load_config, so managed quick_commands / stt would otherwise be ignored). + from hermes_cli import managed_scope yaml_cfg = managed_scope.apply_managed_overlay(yaml_cfg) if not yaml_cfg: return diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py index de5c04485a..305583f486 100644 --- a/tests/gateway/relay/test_explicit_disable.py +++ b/tests/gateway/relay/test_explicit_disable.py @@ -224,21 +224,18 @@ def test_legacy_json_disable_is_advisory_like_other_platforms(profile, monkeypat assert config.platforms[Platform.TELEGRAM].enabled -@pytest.mark.parametrize("user_yaml", ["no-files", "absent", "empty", "null", "list", "malformed", "unreadable", "sibling", "enabled", "disabled"]) +@pytest.mark.parametrize("user_yaml", ["no-files", "absent", "empty", "null", "sibling", "enabled", "disabled"]) @pytest.mark.parametrize("managed_state", ["absent", "url-only", "enabled", "disabled"]) def test_managed_layer_agrees_with_native_config(profile, monkeypatch, user_yaml, managed_state): """Managed leaves override user leaves, not CLI defaults or a second merge policy.""" path = profile / "config.yaml" user_docs = { - "empty": "", "null": "null\n", "list": "- not-a-config\n", - "malformed": "platforms: [\n", + "empty": "", "null": "null\n", "sibling": "platforms:\n relay:\n extra:\n user_sibling: kept\n", "enabled": "platforms:\n relay:\n enabled: true\n", "disabled": "platforms:\n relay:\n enabled: false\n", } - if user_yaml == "unreadable": - path.mkdir() # A directory fails open even when tests run as root. - elif user_yaml not in {"absent", "no-files"}: + if user_yaml not in {"absent", "no-files"}: path.write_text(user_docs[user_yaml]) managed = profile / "managed" managed.mkdir() From 16b56e8e2248f690e372a3750b6755734c86b610 Mon Sep 17 00:00:00 2001 From: Ben Barclay Date: Fri, 11 Sep 2026 10:30:01 +1000 Subject: [PATCH 10/13] test(relay): replace the startup harness with four invariant tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 16×9 side-effect matrix and the 3×4×2 startup run patched ~15 GatewayStartupMixin internals plus gateway.run._hermes_home to drive start(); that is a harness for one revision of run_startup.py, not a contract, and it would break on the next phase split. Keep what the fix promises and nothing else: - the real startup hook (_start_register_plugins_relay_hooks) makes no connector call, registers nothing and leaves GATEWAY_RELAY_* alone under every accepted spelling of the disable (top, nested, string 'false', top-beats-nested, managed-only); - URL-only activation without an 'enabled' key is unchanged (control, green on base); - the standalone predicate and load_gateway_config() are two readers of one rule, and the vetoed relay does not suppress native adapters; - a gateway.json disable stays advisory for relay as for telegram. 218 -> 12 tests; all 15 non-control cases fail on the merge base. --- tests/gateway/relay/test_explicit_disable.py | 360 +++++-------------- 1 file changed, 80 insertions(+), 280 deletions(-) diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py index 305583f486..609f86cfcc 100644 --- a/tests/gateway/relay/test_explicit_disable.py +++ b/tests/gateway/relay/test_explicit_disable.py @@ -1,10 +1,9 @@ -"""Explicit relay opt-out must dominate ambient deployment credentials. +"""``platforms.relay.enabled: false`` beats a deployment-injected relay URL. -Real profile files and production startup/standalone entrypoints; only external -I/O and unrelated gateway services are replaced. No connector is contacted. +Real profile files under a temp HERMES_HOME, the production startup hook and the +standalone predicate. Only the connector HTTP calls are replaced. """ -from types import SimpleNamespace -from unittest.mock import AsyncMock, Mock +from unittest.mock import Mock import json import os @@ -14,30 +13,34 @@ import yaml import gateway.relay as relay from gateway.config import Platform, load_gateway_config from gateway.platform_registry import platform_registry -from gateway.relay.adapter import RelayAdapter -from gateway.relay.descriptor import CapabilityDescriptor, CONTRACT_VERSION -from gateway.relay.ws_transport import WebSocketRelayTransport from gateway.run_startup import GatewayStartupMixin URL = "wss://connector.example/relay" -CREDENTIALS = { - "GATEWAY_RELAY_ID": "shared-gateway", - "GATEWAY_RELAY_INSTANCE_ID": "shared-instance", - "GATEWAY_RELAY_DELIVERY_KEY": "inherited-delivery-key", +DISABLE = {"relay": {"enabled": False}} + +# Every place the loader accepts a relay block, plus the managed overlay. The verdict must be +# the same whichever one the operator used. +SPELLINGS = { + "top": {"platforms": DISABLE}, + "nested": {"gateway": {"platforms": DISABLE}}, + "string-false": {"platforms": {"relay": {"enabled": "false"}}}, + "top-beats-nested": {"platforms": DISABLE, "gateway": {"platforms": {"relay": {"enabled": True}}}}, + "managed": None, # user YAML absent; disable comes from HERMES_MANAGED_DIR } @pytest.fixture def profile(tmp_path, monkeypatch): monkeypatch.setenv("HERMES_HOME", str(tmp_path)) - # Keep the runtime loader on the same real profile as load_gateway_config. - monkeypatch.setattr("gateway.run._hermes_home", tmp_path) for key in list(os.environ): if key.startswith("GATEWAY_RELAY_"): monkeypatch.delenv(key) - for key, value in CREDENTIALS.items(): - monkeypatch.setenv(key, value) + # A deployment stamp: URL + identity provider, no pinned secret, so an + # un-vetoed boot would resolve a token and provision credentials. + monkeypatch.setenv("GATEWAY_RELAY_URL", URL) monkeypatch.setenv("GATEWAY_RELAY_PLATFORMS", "slack") + monkeypatch.setenv("GATEWAY_RELAY_IDP_TOKEN_URL", "https://identity.example/token") + monkeypatch.setenv("SLACK_BOT_TOKEN", "native-test-token") monkeypatch.setattr("hermes_cli.plugins.discover_plugins", lambda: None) monkeypatch.setattr(GatewayStartupMixin, "_register_config_hooks", lambda *a, **k: None) platform_registry.unregister("relay") @@ -45,286 +48,83 @@ def profile(tmp_path, monkeypatch): platform_registry.unregister("relay") -def configure(home, state, source, monkeypatch): - cfg = {"platforms": {"slack": {"enabled": True, "token": "native-test-token"}}, - "slack": {"require_mention": False}} - if state is not None: - cfg["platforms"]["relay"] = {"enabled": state, "extra": {"relay_url": URL}} - if source == "managed-only": - # No user YAML: the managed overlay must still own relay intent before - # the injected URL can exclusively suppress this legacy native Slack. - (home / "gateway.json").write_text(json.dumps({"platforms": {"slack": cfg["platforms"]["slack"]}})) +def write_disable(home, spelling, monkeypatch): + doc = SPELLINGS[spelling] + if doc is None: managed = home / "managed" managed.mkdir() - managed_cfg: dict = {"gateway": {"relay_url": URL}, "slack": {"require_mention": False}} - if state is not None: - managed_cfg["platforms"] = {"relay": {"enabled": state}} - (managed / "config.yaml").write_text(yaml.safe_dump(managed_cfg)) + (managed / "config.yaml").write_text(yaml.safe_dump({"platforms": DISABLE})) monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) - monkeypatch.setenv("GATEWAY_RELAY_URL", URL) - assert not (home / "config.yaml").exists() return - if source == "env": - monkeypatch.setenv("GATEWAY_RELAY_URL", URL) - elif source == "managed": - managed = home / "managed" - managed.mkdir() - (managed / "config.yaml").write_text(yaml.safe_dump({"gateway": {"relay_url": URL}})) - monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) - else: - cfg["gateway"] = {"relay_url": URL} - (home / "config.yaml").write_text(yaml.safe_dump(cfg), encoding="utf-8") + (home / "config.yaml").write_text(yaml.safe_dump(doc)) -def descriptor(): - return CapabilityDescriptor(contract_version=CONTRACT_VERSION, platform="slack", - label="Relay", max_message_length=4096, - supports_draft_streaming=False, supports_edit=True, - supports_threads=False, markdown_dialect="plain", len_unit="chars") - - -@pytest.mark.asyncio -@pytest.mark.parametrize("state", [False, True, None], ids=["disabled", "enabled", "legacy"]) -@pytest.mark.parametrize("source", ["yaml", "env", "managed", "managed-only"]) -@pytest.mark.parametrize("pinned", [False, True], ids=["unprovisioned", "inherited-secret"]) -async def test_production_startup_respects_profile_opt_out(profile, monkeypatch, state, source, pinned): - configure(profile, state, source, monkeypatch) - if state is True and source != "managed-only": - # The winning top-level enable must override a lower-priority disable. - path = profile / "config.yaml" - cfg = yaml.safe_load(path.read_text()) - cfg.setdefault("gateway", {})["platforms"] = {"relay": {"enabled": False}} - path.write_text(yaml.safe_dump(cfg)) - if pinned: - monkeypatch.setenv("GATEWAY_RELAY_SECRET", "a" * 64) +@pytest.mark.parametrize("spelling", list(SPELLINGS)) +def test_disabled_relay_startup_hook_has_no_side_effects(profile, monkeypatch, spelling): + write_disable(profile, spelling, monkeypatch) + http = Mock(side_effect=AssertionError("disabled relay reached the connector")) + monkeypatch.setattr("urllib.request.urlopen", http) + monkeypatch.setattr(relay, "_resolve_relay_identity_token", http) before = {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} - token = Mock(return_value="identity-token") - provision = Mock(return_value={"gatewayId": "provisioned-gateway", "secret": "b" * 64, - "deliveryKey": "new-delivery-key"}) - policy = Mock(return_value=200) - monkeypatch.setattr(relay, "_resolve_relay_identity_token", token) + + GatewayStartupMixin._start_register_plugins_relay_hooks() + + http.assert_not_called() + assert not platform_registry.is_registered("relay") + assert {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} == before + # The test seam and an explicit URL do not override the operator either. + assert relay.register_relay_adapter(force=True, url=URL) is False + # Standalone routing (cron preflight) agrees: nothing is relay-fronted. + assert relay.relay_fronted_platforms() == set() + + +def test_url_only_activation_is_unchanged(profile, monkeypatch): + """Control: with no ``enabled`` key the injected URL still activates relay.""" + (profile / "config.yaml").write_text(yaml.safe_dump({"platforms": {"relay": {"extra": {"note": "kept"}}}})) + provision = Mock(return_value={"gatewayId": "g", "secret": "b" * 64, "deliveryKey": "d"}) + monkeypatch.setattr(relay, "_resolve_relay_identity_token", Mock(return_value="identity-token")) monkeypatch.setattr(relay, "_post_provision", provision) - monkeypatch.setattr(relay, "_post_policy", policy) - relay_connect = AsyncMock(return_value=True) - monkeypatch.setattr(WebSocketRelayTransport, "connect", relay_connect) - monkeypatch.setattr(WebSocketRelayTransport, "handshake", AsyncMock(return_value=descriptor())) - monkeypatch.setattr(RelayAdapter, "_start_revocation_monitor", lambda self: None) - native = SimpleNamespace(connect=AsyncMock(return_value=True), send_path_degraded=False, - send=AsyncMock(return_value={"success": True})) + monkeypatch.setattr(relay, "_post_policy", Mock(return_value=200)) - # Execute start(), including real relay bootstrap, prefilter, connect and - # aggregation. Suppress only unrelated recovery/watchers/status services. - runner = GatewayStartupMixin() - runner.config = load_gateway_config() - runner.adapters = {} - runner._failed_platforms = {} - runner.delivery_router = SimpleNamespace(adapters={}) - for name in ("_start_install_faulthandler", "_start_log_startup_environment", - "_start_startup_warmup", "_wire_adapter_handlers", "_update_platform_runtime_status", - "_wire_teams_pipeline_runtime", "_install_plugin_message_injector", - "_update_runtime_status", "_start_spawn_background_watchers"): - monkeypatch.setattr(runner, name, Mock(), raising=False) - runner._start_check_access_policy = lambda: False - runner._abort_startup_if_shutdown_requested = AsyncMock(return_value=False) - runner._multiplex_on = lambda: False - runner._startup_should_abort = lambda: False + GatewayStartupMixin._start_register_plugins_relay_hooks() - async def recover(): - runner._start_register_plugins_relay_hooks() - - async def connect(adapter, platform): - return await adapter.connect() - - async def secondary(count, skipped): - return False, count - - runner._start_recover_previous_run = recover - runner._connect_initial_adapter_with_timeout = connect - runner._start_secondary_profiles = secondary - runner._start_finish_wiring = AsyncMock() - runner._start_handle_no_connections = lambda *args: False - runner._publish_primary_adapter = lambda p, a: runner.adapters.__setitem__(p, a) - runner._create_adapter = lambda p, c: (platform_registry.create_adapter("relay", c) - if p == Platform.RELAY else native) - assert await runner.start() is True - - if state is False: - token.assert_not_called() - provision.assert_not_called() - policy.assert_not_called() - relay_connect.assert_not_awaited() - assert not platform_registry.is_registered("relay") - assert Platform.RELAY not in runner.adapters - assert Platform.RELAY not in runner._failed_platforms - assert {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} == before - native.connect.assert_awaited_once() - assert runner.adapters[Platform.SLACK] is native - from cron.scheduler_delivery import _resolve_target_transport - - resolved, error = _resolve_target_transport( - {"id": "native-job"}, Platform.SLACK, "slack", {"chat_id": "channel"}, {}, runner.config, - ) - assert error is None - assert resolved[1] is runner.config.platforms[Platform.SLACK] - # Deliver through the native adapter published by real startup, not just - # a helper predicate. Standalone routing above must also remain enabled. - resolved, error = _resolve_target_transport( - {"id": "native-job"}, Platform.SLACK, "slack", {"chat_id": "channel"}, - runner.adapters, runner.config, - ) - assert error is None - assert not resolved[0].is_relay - assert await resolved[0].send(Platform.SLACK, "channel", "native receipt", {}) == {"success": True} - native.send.assert_awaited_once_with("channel", "native receipt", metadata={}) - else: - assert platform_registry.is_registered("relay") - assert provision.call_count == (0 if pinned else 1) - assert token.call_count == provision.call_count - policy.assert_called_once() - # Existing env-exclusive behavior is unchanged. YAML activation is additive. - assert native.connect.await_count == (0 if source in {"env", "managed-only"} else 1) - # The env path already auto-enables relay in the platform loader. - if source in {"env", "managed-only"} or state is True: - relay_connect.assert_awaited_once() - assert Platform.RELAY in runner.adapters - if source in {"env", "managed-only"}: - from cron.scheduler_delivery import _resolve_target_transport - - resolved, error = _resolve_target_transport( - {"id": "relay-job"}, Platform.SLACK, "slack", {"chat_id": "channel"}, {}, runner.config, - ) - assert resolved is None - assert "relay-fronted" in error + provision.assert_called_once() + assert platform_registry.is_registered("relay") + assert relay.relay_fronted_platforms() == {"slack"} -@pytest.mark.parametrize("yaml_state", ["absent", "empty", "sibling", "enabled"]) -@pytest.mark.parametrize("disabled", [False, "false"]) -def test_legacy_json_disable_is_advisory_like_other_platforms(profile, monkeypatch, yaml_state, disabled): +@pytest.mark.parametrize("spelling", list(SPELLINGS)) +def test_predicate_agrees_with_loader_and_keeps_native_adapters(profile, monkeypatch, spelling): + """The standalone predicate and ``load_gateway_config()`` are two readers of one rule, and an + opted-out relay does not own the profile's native connections.""" + write_disable(profile, spelling, monkeypatch) + config = load_gateway_config() + + assert relay.relay_explicitly_disabled() is True + assert config.platforms[Platform.RELAY].enabled is False + # Without the veto GATEWAY_RELAY_URL disables every directly-connected platform. + assert config.platforms[Platform.SLACK].enabled is True + + from cron.scheduler_delivery import _resolve_target_transport + + resolved, error = _resolve_target_transport( + {"id": "job"}, Platform.SLACK, "slack", {"chat_id": "channel"}, {}, config, + ) + assert error is None + assert resolved[1] is config.platforms[Platform.SLACK] + + +def test_legacy_json_disable_is_advisory_like_other_platforms(profile, monkeypatch): (profile / "gateway.json").write_text(json.dumps({"platforms": { - "relay": {"enabled": disabled}, - "slack": {"enabled": True, "token": "native-test-token"}, + "relay": {"enabled": False}, "telegram": {"enabled": False}, }})) - cfg = {} - if yaml_state == "sibling": - cfg = {"platforms": {"relay": {"extra": {"relay_url": URL}}}} - elif yaml_state == "enabled": - cfg = {"platforms": {"relay": {"enabled": True}}} - if yaml_state != "absent": - (profile / "config.yaml").write_text(yaml.safe_dump(cfg)) - monkeypatch.setenv("GATEWAY_RELAY_URL", URL) monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "native-telegram-test-token") monkeypatch.setenv("GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS", "true") config = load_gateway_config() - # A legacy gateway.json ``enabled`` is advisory for relay exactly as it is for telegram: - # env presence (the URL / the token) re-enables both. Only YAML sets ``_enabled_explicit``. + + # Only a YAML ``enabled`` key sets ``_enabled_explicit``; env presence (the URL, the token) + # re-enables a gateway.json disable for relay exactly as it does for telegram. assert relay.relay_explicitly_disabled() is False - assert config.platforms[Platform.RELAY].enabled - assert config.platforms[Platform.SLACK].enabled - assert config.platforms[Platform.TELEGRAM].enabled - - -@pytest.mark.parametrize("user_yaml", ["no-files", "absent", "empty", "null", "sibling", "enabled", "disabled"]) -@pytest.mark.parametrize("managed_state", ["absent", "url-only", "enabled", "disabled"]) -def test_managed_layer_agrees_with_native_config(profile, monkeypatch, user_yaml, managed_state): - """Managed leaves override user leaves, not CLI defaults or a second merge policy.""" - path = profile / "config.yaml" - user_docs = { - "empty": "", "null": "null\n", - "sibling": "platforms:\n relay:\n extra:\n user_sibling: kept\n", - "enabled": "platforms:\n relay:\n enabled: true\n", - "disabled": "platforms:\n relay:\n enabled: false\n", - } - if user_yaml not in {"absent", "no-files"}: - path.write_text(user_docs[user_yaml]) - managed = profile / "managed" - managed.mkdir() - monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) - if managed_state != "absent": - block: dict = {"extra": {"relay_url": "${GATEWAY_RELAY_URL}", "managed_sibling": "pinned"}} - if managed_state != "url-only": - block["enabled"] = managed_state == "enabled" - (managed / "config.yaml").write_text(yaml.safe_dump({ - "platforms": {"relay": block}, - "gateway": {"max_concurrent_sessions": 7}, - })) - if user_yaml == "no-files": - monkeypatch.setenv("SLACK_BOT_TOKEN", "native-test-token") - else: - (profile / "gateway.json").write_text(json.dumps({"platforms": { - "slack": {"enabled": True, "token": "native-test-token"}, - "telegram": {"enabled": False}, - }})) - monkeypatch.setenv("GATEWAY_RELAY_URL", URL) - monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "native-telegram-test-token") - # An absent managed enabled leaf must not introduce DEFAULT_CONFIG's false. - disabled = managed_state == "disabled" or ( - managed_state in {"absent", "url-only"} and user_yaml == "disabled" - ) - config = load_gateway_config() - assert relay.relay_explicitly_disabled() is disabled - assert config.platforms[Platform.RELAY].enabled is not disabled - assert config.platforms[Platform.SLACK].enabled is disabled - assert config.platforms[Platform.TELEGRAM].enabled is disabled - if managed_state != "absent": - assert config.max_concurrent_sessions == 7 - assert config.platforms[Platform.RELAY].extra["managed_sibling"] == "pinned" - assert config.platforms[Platform.RELAY].extra["relay_url"] == URL - if user_yaml == "sibling": - assert config.platforms[Platform.RELAY].extra["user_sibling"] == "kept" - - -@pytest.mark.asyncio -@pytest.mark.parametrize("entry", ["url", "provision", "policy", "registration", "forced-registration", "fronted"]) -@pytest.mark.parametrize("spelling", ["top", "nested", "normalized", "yaml-wins", "gateway-relay", "top-relay", "managed-disable", "sibling-keeps-disable"]) -async def test_disabled_standalone_paths_have_no_relay_side_effects(profile, monkeypatch, entry, spelling): - block = {"enabled": "false" if spelling == "normalized" else False} - cfg = {"gateway": {"relay_url": URL}} - if spelling == "nested": - cfg["gateway"]["platforms"] = {"relay": block} - elif spelling == "gateway-relay": - cfg["gateway"]["relay"] = block - cfg["platforms"] = {"relay": {"enabled": True}} - elif spelling == "top-relay": - cfg["relay"] = block - cfg["gateway"]["relay"] = {"enabled": True} - elif spelling == "managed-disable": - cfg["platforms"] = {"relay": {"enabled": True}} - managed = profile / "managed" - managed.mkdir() - (managed / "config.yaml").write_text(yaml.safe_dump({"platforms": {"relay": block}})) - monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed)) - elif spelling == "sibling-keeps-disable": - cfg["gateway"]["platforms"] = {"relay": block} - cfg["platforms"] = {"relay": {"extra": {"relay_url": URL}}} - else: - cfg["platforms"] = {"relay": block} - if spelling == "yaml-wins": - cfg["gateway"]["platforms"] = {"relay": {"enabled": True}} - (profile / "config.yaml").write_text(yaml.safe_dump(cfg), encoding="utf-8") - monkeypatch.setenv("GATEWAY_RELAY_URL", URL) - monkeypatch.setenv("GATEWAY_RELAY_IDP_TOKEN_URL", "https://identity.example/token") - before = {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} - http = Mock(side_effect=AssertionError("disabled relay attempted HTTP")) - monkeypatch.setattr("urllib.request.urlopen", http) - provision = Mock(return_value={"secret": "b" * 64, "gatewayId": "replaced"}) - monkeypatch.setattr(relay, "_post_provision", provision) - - if entry == "url": - assert relay.relay_url() is None - elif entry == "provision": - assert relay.self_provision_relay() is False - elif entry == "policy": - monkeypatch.setenv("GATEWAY_RELAY_SECRET", "a" * 64) - before["GATEWAY_RELAY_SECRET"] = "a" * 64 - monkeypatch.setenv("SLACK_ALLOW_BOTS", "all") - assert relay.send_relay_policy() is False - elif entry in {"registration", "forced-registration"}: - assert relay.register_relay_adapter(url=URL, force=entry == "forced-registration") is False - assert not platform_registry.is_registered("relay") - elif entry == "fronted": - assert relay.relay_fronted_platforms() == set() - - http.assert_not_called() - provision.assert_not_called() - assert {k: v for k, v in os.environ.items() if k.startswith("GATEWAY_RELAY_")} == before + assert config.platforms[Platform.RELAY].enabled is True + assert config.platforms[Platform.TELEGRAM].enabled is True From 5edf794e6b7f39f96855d79807ad0cc9e058d187 Mon Sep 17 00:00:00 2001 From: Ben Barclay Date: Fri, 11 Sep 2026 10:30:29 +1000 Subject: [PATCH 11/13] test: restore the untouched streaming nested-config test The rewrite existed only because the PR swapped load_yaml_layer's YAML read for hermes_cli.config.read_user_config_raw, which broke the file's mocks. The loader keeps its own read now, so the #25676 regression test returns to its committed form; out of scope for a relay fix. --- tests/test_gateway_streaming_nested_config.py | 58 ++++++++----------- 1 file changed, 23 insertions(+), 35 deletions(-) diff --git a/tests/test_gateway_streaming_nested_config.py b/tests/test_gateway_streaming_nested_config.py index 8caed2ea09..b4658b755a 100644 --- a/tests/test_gateway_streaming_nested_config.py +++ b/tests/test_gateway_streaming_nested_config.py @@ -1,54 +1,42 @@ """Regression test for #25676 — nested gateway.streaming config must be loaded.""" from pathlib import Path -from textwrap import dedent - -import pytest +from unittest.mock import patch, MagicMock -@pytest.fixture -def load_yaml(tmp_path, monkeypatch): - """Exercise the raw loader, not a particular YAML parser implementation.""" + +def _load_with_yaml_dict(yaml_dict: dict): + """Patch filesystem so load_gateway_config() sees *yaml_dict* as config.yaml.""" from gateway.config import load_gateway_config - monkeypatch.setattr(Path, "home", lambda: tmp_path) - monkeypatch.setenv("HERMES_HOME", str(tmp_path)) + fake_home = Path("/tmp/fake_hermes_home_25676") - def load(text): - (tmp_path / "config.yaml").write_text(dedent(text), encoding="utf-8") - return load_gateway_config() + def fake_exists(self): + return str(self).endswith("config.yaml") - return load + with patch("gateway.config.get_hermes_home", return_value=fake_home), \ + patch.object(Path, "exists", fake_exists), \ + patch("builtins.open", create=True) as mock_file: + mock_file.return_value.__enter__ = lambda s: s + mock_file.return_value.__exit__ = MagicMock(return_value=False) + with patch("yaml.safe_load", return_value=yaml_dict): + return load_gateway_config() class TestStreamingConfigNested: - def test_top_level_streaming(self, load_yaml): - cfg = load_yaml("streaming: {enabled: true, transport: draft}") + def test_top_level_streaming(self): + cfg = _load_with_yaml_dict({"streaming": {"enabled": True, "transport": "draft"}}) assert cfg.streaming.enabled is True assert cfg.streaming.transport == "draft" - def test_top_level_takes_precedence(self, load_yaml): - cfg = load_yaml(""" - streaming: {enabled: true, transport: edit} - gateway: - streaming: {enabled: false, transport: draft} - """) + def test_top_level_takes_precedence(self): + cfg = _load_with_yaml_dict({ + "streaming": {"enabled": True, "transport": "edit"}, + "gateway": {"streaming": {"enabled": False, "transport": "draft"}}, + }) assert cfg.streaming.enabled is True assert cfg.streaming.transport == "edit" - def test_nested_only_streaming(self, load_yaml): - cfg = load_yaml(""" - gateway: - streaming: {enabled: true, transport: draft} - """) - assert cfg.streaming.enabled is True - assert cfg.streaming.transport == "draft" - - def test_explicit_disable_preserves_transport(self, load_yaml): - cfg = load_yaml("streaming: {enabled: false, mode: auto, transport: draft}") - assert cfg.streaming.enabled is False - assert cfg.streaming.transport == "draft" - class TestStreamingModeAlias: """``streaming: {mode: ...}`` is an alias that also implies ``enabled``. @@ -117,10 +105,10 @@ class TestStreamingYamlBooleanQuirk: assert sc.transport == "auto" - def test_loader_normalizes_bare_yaml_off(self, load_yaml): + def test_loader_normalizes_bare_yaml_off(self): """End-to-end through load_gateway_config(): unquoted ``mode: off`` (a YAML boolean) must keep streaming disabled.""" - cfg = load_yaml("streaming: {mode: off}") + cfg = _load_with_yaml_dict({"streaming": {"mode": False}}) assert cfg.streaming.enabled is False assert cfg.streaming.transport == "off" From 7ea67e97f446eca046755e799b24ee52a471204e Mon Sep 17 00:00:00 2001 From: Ben Barclay Date: Fri, 11 Sep 2026 10:30:41 +1000 Subject: [PATCH 12/13] docs(relay): describe the opt-out at its real boundary Drop the claims about reconnects and media handling that no longer have code behind them; state where the verdict is read and what a gateway.json disable does. --- website/docs/user-guide/messaging/relay.md | 31 +++++++++++----------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/website/docs/user-guide/messaging/relay.md b/website/docs/user-guide/messaging/relay.md index 8767cfdece..e2b548a2ab 100644 --- a/website/docs/user-guide/messaging/relay.md +++ b/website/docs/user-guide/messaging/relay.md @@ -96,8 +96,9 @@ environment. ## Configuration -Relay activation remains URL-based for compatibility, unless the effective -platform configuration explicitly disables it: +Relay activates when a connector relay URL is configured. To keep a profile off +the relay even when the deployment injects a URL, disable the platform in +`config.yaml`: ```yaml platforms: @@ -105,21 +106,19 @@ platforms: enabled: false ``` -- **Explicit disable wins.** `enabled: false` prevents automatic identity-token - resolution, provisioning, credential mutation, registration, policy calls, - connection attempts, reconnects, and relay media handling, even with an - injected `gateway.relay_url` or `GATEWAY_RELAY_URL`. -- **Native platforms remain available.** A disabled relay does not suppress - native messaging adapters or claim standalone delivery destinations through - inherited relay identity variables. Inherited credentials are left unchanged. -- **Existing activation is preserved.** `enabled: true` still requires a - connector URL. Omitting `enabled` keeps the existing URL-based behavior. +- **Explicit disable wins.** With `enabled: false` the gateway does not resolve + an identity token, provision or rewrite `GATEWAY_RELAY_*` credentials, register + the relay adapter or send the relevance policy — even with `gateway.relay_url` + or `GATEWAY_RELAY_URL` set. Native messaging adapters connect as if no relay + URL were present, and cron delivery treats no platform as relay-fronted. +- **Omitting `enabled` keeps URL-based activation.** `enabled: true` still needs + a connector URL. A `gateway.json` `enabled: false` is advisory, as for every + other platform; put the opt-out in `config.yaml` (user or managed). -The decision uses the gateway's merged platform configuration, including managed -settings and supported nested platform sections. Restart the gateway after -changing this setting. This is not a live teardown mechanism for an already-open -socket. The explicit `hermes gateway enroll` command remains available while -runtime relay is disabled. +The verdict is read once at startup from the same merged platform configuration +the gateway uses (top-level or `gateway.platforms` block, managed overlay). +Restart the gateway after changing it; an open relay socket is not torn down. +`hermes gateway enroll` remains available while runtime relay is disabled. | Setting | Where | Meaning | |---------|-------|---------| From 6f5dda1aee0264fbd75143589b4ab75b9a558cae Mon Sep 17 00:00:00 2001 From: Ben Barclay Date: Fri, 11 Sep 2026 10:45:33 +1000 Subject: [PATCH 13/13] fix(relay): read the opt-out through the loader's own YAML reader MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit relay_explicitly_disabled() went through hermes_cli.config.read_raw_config, which turns a malformed config.yaml into {} and then applies the managed overlay. load_gateway_config() raises on the same file and falls back to env + gateway.json WITHOUT the managed layer. With a managed relay.enabled: false and an injected URL the two readers disagreed: the loader kept relay enabled and suppressed native Slack, while startup refused to register relay — a profile with no route at all. Extract the loader's file selection into config_loader.read_yaml_layers() and have both consumers use it; the predicate mirrors the loader's fallback (no YAML layer) on a parse error. Regression test fails on the previous predicate. --- gateway/config_loader.py | 19 ++++++++++++++----- gateway/relay/__init__.py | 17 +++++++++++------ tests/gateway/relay/test_explicit_disable.py | 13 +++++++++++++ website/docs/user-guide/messaging/relay.md | 4 ++-- 4 files changed, 40 insertions(+), 13 deletions(-) diff --git a/gateway/config_loader.py b/gateway/config_loader.py index dd638e4b96..fd276eb431 100644 --- a/gateway/config_loader.py +++ b/gateway/config_loader.py @@ -335,10 +335,14 @@ def bridge_core_env_settings(yaml_cfg: dict, platforms_data: dict) -> None: os.environ["SIGNAL_REQUIRE_MENTION"] = str(signal_cfg["require_mention"]).lower() -def load_yaml_layer(home: Path, gw_data: dict) -> None: - """Overlay ``config.yaml`` + managed YAML onto *gw_data* in place. Raises on a malformed user - file (caller warns + falls back). An ABSENT user file is an empty layer, not a reason to skip - the administrator's values: a fleet host with no ``config.yaml`` must still honor them. +def read_yaml_layers(home: Path) -> dict: + """User ``config.yaml`` with the managed overlay applied — the YAML the gateway loader sees. + + Raises on a malformed user file (the loader then falls back to env + gateway.json WITHOUT the + managed layer). An ABSENT user file is an empty layer, not a reason to skip the administrator's + values: a fleet host with no ``config.yaml`` must still honor them. Any pre-activation predicate + (``gateway.relay.relay_explicitly_disabled``) reads through here so it cannot disagree with + ``load_gateway_config()`` on which files count. """ import yaml @@ -351,7 +355,12 @@ def load_yaml_layer(home: Path, gw_data: dict) -> None: # Managed scope: overlay administrator-pinned values (this loader bypasses # hermes_cli.config.load_config, so managed quick_commands / stt would otherwise be ignored). from hermes_cli import managed_scope - yaml_cfg = managed_scope.apply_managed_overlay(yaml_cfg) + return managed_scope.apply_managed_overlay(yaml_cfg) + + +def load_yaml_layer(home: Path, gw_data: dict) -> None: + """Overlay ``read_yaml_layers`` onto *gw_data* in place. Raises on any failure (caller warns + falls back).""" + yaml_cfg = read_yaml_layers(home) if not yaml_cfg: return diff --git a/gateway/relay/__init__.py b/gateway/relay/__init__.py index 148715a65a..34722d34b1 100644 --- a/gateway/relay/__init__.py +++ b/gateway/relay/__init__.py @@ -73,18 +73,23 @@ def _env_or_cfg_url(env_var: str, cfg_key: str) -> Optional[str]: def relay_explicitly_disabled() -> bool: """``platforms.relay.enabled: false`` in the profile's YAML (user or managed). - Same merge and boolean normalization as the gateway loader, minus its env/plugin - side effects, so a standalone scheduler can ask without bootstrapping the gateway. + Same files, merge and boolean normalization as the gateway loader (a malformed user + file drops the whole YAML layer there too), minus its env/plugin side effects, so a + standalone scheduler can ask without bootstrapping the gateway. Mirrors the loader's ``_enabled_explicit`` rule: only a YAML ``enabled`` key is authoritative — a legacy ``gateway.json`` block is advisory for relay exactly as it is for every other platform, and an absent key keeps URL-only activation. """ from gateway.config import Platform, PlatformConfig - from gateway.config_loader import bridge_platform_shared_keys, merge_platform_sections - from hermes_cli.config import read_raw_config - from hermes_cli.managed_scope import apply_managed_overlay + from gateway.config_loader import bridge_platform_shared_keys, merge_platform_sections, read_yaml_layers + from hermes_constants import get_hermes_home - cfg = apply_managed_overlay(read_raw_config()) + try: + cfg = read_yaml_layers(get_hermes_home()) + except Exception: # noqa: BLE001 - same fallback as load_gateway_config: no YAML layer at all + return False + if not isinstance(cfg, dict): + return False gateway = cfg.get("gateway") if isinstance(cfg.get("gateway"), dict) else {} platforms = merge_platform_sections(cfg, gateway, {}) bridge_platform_shared_keys(cfg, gateway.get("platforms"), {}, platforms, [Platform.RELAY]) diff --git a/tests/gateway/relay/test_explicit_disable.py b/tests/gateway/relay/test_explicit_disable.py index 609f86cfcc..fb3114b264 100644 --- a/tests/gateway/relay/test_explicit_disable.py +++ b/tests/gateway/relay/test_explicit_disable.py @@ -128,3 +128,16 @@ def test_legacy_json_disable_is_advisory_like_other_platforms(profile, monkeypat assert relay.relay_explicitly_disabled() is False assert config.platforms[Platform.RELAY].enabled is True assert config.platforms[Platform.TELEGRAM].enabled is True + + +def test_malformed_user_yaml_drops_the_yaml_layer_for_both_readers(profile, monkeypatch): + """The loader falls back to env + gateway.json WITHOUT the managed layer on a malformed user + file; the predicate must fall back the same way or startup suppresses native adapters for a + relay it then refuses to register.""" + (profile / "config.yaml").write_text("platforms: [\n") + write_disable(profile, "managed", monkeypatch) + config = load_gateway_config() + + assert relay.relay_explicitly_disabled() is False + assert config.platforms[Platform.RELAY].enabled is True + assert relay.relay_url() == URL diff --git a/website/docs/user-guide/messaging/relay.md b/website/docs/user-guide/messaging/relay.md index e2b548a2ab..4ef23c6f60 100644 --- a/website/docs/user-guide/messaging/relay.md +++ b/website/docs/user-guide/messaging/relay.md @@ -115,8 +115,8 @@ platforms: a connector URL. A `gateway.json` `enabled: false` is advisory, as for every other platform; put the opt-out in `config.yaml` (user or managed). -The verdict is read once at startup from the same merged platform configuration -the gateway uses (top-level or `gateway.platforms` block, managed overlay). +The verdict comes from the same files and merge the gateway loader uses (top-level +or `gateway.platforms` block, managed overlay) and is applied at activation time. Restart the gateway after changing it; an open relay socket is not torn down. `hermes gateway enroll` remains available while runtime relay is disabled.