Merge pull request #105839 from victor-kyriazakos/fix/relay-explicit-disable

fix(relay): honor explicit profile disable before relay startup
This commit is contained in:
Ben Barclay
2026-09-11 14:02:08 +10:00
committed by GitHub
7 changed files with 299 additions and 15 deletions
+5 -1
View File
@@ -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
+21 -7
View File
@@ -335,20 +335,34 @@ 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`` onto *gw_data* in place. Raises on any failure (caller warns + falls back)."""
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
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 {}
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)
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
gateway_section = yaml_cfg.get("gateway")
bridge_toplevel_keys(yaml_cfg, gateway_section, gw_data)
+40 -3
View File
@@ -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:
"""``platforms.relay.enabled: false`` in the profile's YAML (user or managed).
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, read_yaml_layers
from hermes_constants import get_hermes_home
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])
block = platforms.get("relay")
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]:
"""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"}
@@ -641,9 +675,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
+2 -1
View File
@@ -876,7 +876,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
+64
View File
@@ -0,0 +1,64 @@
"""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", "managed-only", "scoped"])
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", "managed-only"}:
(home / "config.yaml").write_text(yaml.safe_dump(config))
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")
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] == "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": {}}
@@ -0,0 +1,143 @@
"""``platforms.relay.enabled: false`` beats a deployment-injected relay URL.
Real profile files under a temp HERMES_HOME, the production startup hook and the
standalone predicate. Only the connector HTTP calls are replaced.
"""
from unittest.mock import Mock
import json
import os
import pytest
import yaml
import gateway.relay as relay
from gateway.config import Platform, load_gateway_config
from gateway.platform_registry import platform_registry
from gateway.run_startup import GatewayStartupMixin
URL = "wss://connector.example/relay"
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))
for key in list(os.environ):
if key.startswith("GATEWAY_RELAY_"):
monkeypatch.delenv(key)
# 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")
yield tmp_path
platform_registry.unregister("relay")
def write_disable(home, spelling, monkeypatch):
doc = SPELLINGS[spelling]
if doc is None:
managed = home / "managed"
managed.mkdir()
(managed / "config.yaml").write_text(yaml.safe_dump({"platforms": DISABLE}))
monkeypatch.setenv("HERMES_MANAGED_DIR", str(managed))
return
(home / "config.yaml").write_text(yaml.safe_dump(doc))
@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_")}
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", Mock(return_value=200))
GatewayStartupMixin._start_register_plugins_relay_hooks()
provision.assert_called_once()
assert platform_registry.is_registered("relay")
assert relay.relay_fronted_platforms() == {"slack"}
@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": False},
"telegram": {"enabled": False},
}}))
monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "native-telegram-test-token")
monkeypatch.setenv("GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS", "true")
config = load_gateway_config()
# 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 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
+24 -3
View File
@@ -96,12 +96,33 @@ 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 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:
relay:
enabled: false
```
- **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 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.
| 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`). |