feat(relay): declare relevance policy to the connector + document the management plane (#51248)
The gateway half of Phase 6 Unit ζ: project the agent's existing relevance
knobs into the connector's platform-agnostic vocabulary and declare them at boot
over the /relay/policy route, so the SAME mention-gating / free-response /
allow-bots behavior the agent applies directly also governs relay delivery (and
excluded chatter never wakes a scaled-to-zero agent).
- gateway/relay/__init__.py:
- relay_relevance_policy(): project require_mention -> requireAddress,
free_response_channels -> freeResponseScopes, {PLATFORM}_ALLOW_BOTS in
{mentions,all} -> allowOtherBots. Reads the fronted platform's config block
+ bridged top-level keys. Returns None when all-default (the connector's
quiet default already matches) or no concrete platform is fronted.
- send_relay_policy(): POST /relay/policy authenticated with the gateway's own
per-gateway upgrade token (make_upgrade_token — same bearer as the WS
upgrade), so the connector attaches it to the authenticated instance, never
a body-asserted id. Re-declares every boot (self-healing, full replace).
NEVER raises, NEVER blocks boot — relevance is an optimization layered on
the δ/ε authorization gate. Reuses the per-gateway secret + the
/relay/provision host; no new inbound surface, no new credential.
- _policy_url(): ws(s)://…/relay -> http(s)://…/relay/policy.
- gateway/run.py: call send_relay_policy() after register_relay_adapter()
succeeds (the secret is resolved by then).
- docs/relay-connector-contract.md: new §7 documenting per-instance delivery +
the management plane (/manage/* + /relay/policy) + the relevance-declaration
contract; versioning renumbered to §8. Contract conformance test stays green
(§2/§3 tables untouched).
Tests: +12 (projection mapping incl. comma-string + top-level fallback; send
auth/skip/fail-soft/non-200). Full relay suite 118 pass. The connector route is
already E2E-proven (connector repo gateway_policy_driver.py); this adds the real
gateway send-path it pairs with.
This completes Phase 6 (Team Gateway per-user isolation) end to end.
This commit is contained in:
Ben Barclay
GitHub
parent
211ba9c7d3
commit
45bc4fb37f
4 changed files with 472 additions and 1 deletions
192
tests/gateway/relay/test_relay_policy_send.py
Normal file
192
tests/gateway/relay/test_relay_policy_send.py
Normal file
|
|
@ -0,0 +1,192 @@
|
|||
"""Unit tests for the gateway-side relay relevance-policy declaration (Phase 6 ζ).
|
||||
|
||||
Covers gateway.relay.relay_relevance_policy() (the projection of the agent's
|
||||
mention-gating / free-response / allow-bots config into the connector's generic
|
||||
vocabulary) and send_relay_policy() (the boot-time POST to /relay/policy). The
|
||||
connector HTTP POST is monkeypatched; the cross-repo E2E (connector repo,
|
||||
gateway_policy_driver.py) exercises the real route. These prove the PROJECTION
|
||||
mapping, the auth/skip logic, and the fail-soft boot behaviour.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
|
||||
import gateway.relay as relay
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _clean_env(monkeypatch):
|
||||
for k in (
|
||||
"GATEWAY_RELAY_URL",
|
||||
"GATEWAY_RELAY_ID",
|
||||
"GATEWAY_RELAY_SECRET",
|
||||
"GATEWAY_RELAY_PLATFORM",
|
||||
"GATEWAY_RELAY_BOT_ID",
|
||||
"DISCORD_ALLOW_BOTS",
|
||||
):
|
||||
monkeypatch.delenv(k, raising=False)
|
||||
monkeypatch.setattr("gateway.run._load_gateway_config", lambda: {}, raising=False)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# relay_relevance_policy() — the projection
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
def test_projection_maps_require_mention_and_free_response(monkeypatch):
|
||||
monkeypatch.setenv("GATEWAY_RELAY_PLATFORM", "discord")
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"discord": {"require_mention": True, "free_response_channels": ["c-support", "c-help"]}},
|
||||
raising=False,
|
||||
)
|
||||
pol = relay.relay_relevance_policy()
|
||||
assert pol == {
|
||||
"platform": "discord",
|
||||
"requireAddress": True,
|
||||
"freeResponseScopes": ["c-support", "c-help"],
|
||||
"allowOtherBots": False,
|
||||
}
|
||||
|
||||
|
||||
def test_projection_allow_other_bots_from_env(monkeypatch):
|
||||
monkeypatch.setenv("GATEWAY_RELAY_PLATFORM", "discord")
|
||||
monkeypatch.setenv("DISCORD_ALLOW_BOTS", "all")
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"discord": {"require_mention": True}},
|
||||
raising=False,
|
||||
)
|
||||
pol = relay.relay_relevance_policy()
|
||||
assert pol is not None and pol["allowOtherBots"] is True
|
||||
|
||||
|
||||
def test_projection_comma_string_free_response(monkeypatch):
|
||||
monkeypatch.setenv("GATEWAY_RELAY_PLATFORM", "discord")
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"discord": {"free_response_channels": "c1, c2 ,c3"}},
|
||||
raising=False,
|
||||
)
|
||||
pol = relay.relay_relevance_policy()
|
||||
assert pol is not None and pol["freeResponseScopes"] == ["c1", "c2", "c3"]
|
||||
|
||||
|
||||
def test_projection_falls_back_to_top_level_require_mention(monkeypatch):
|
||||
monkeypatch.setenv("GATEWAY_RELAY_PLATFORM", "discord")
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"require_mention": True}, # top-level, no discord: block
|
||||
raising=False,
|
||||
)
|
||||
pol = relay.relay_relevance_policy()
|
||||
assert pol is not None and pol["requireAddress"] is True
|
||||
|
||||
|
||||
def test_projection_none_when_all_default(monkeypatch):
|
||||
# No require_mention, no free-response, no allow-bots ⇒ nothing to declare
|
||||
# (the connector's quiet default already matches).
|
||||
monkeypatch.setenv("GATEWAY_RELAY_PLATFORM", "discord")
|
||||
monkeypatch.setattr("gateway.run._load_gateway_config", lambda: {"discord": {}}, raising=False)
|
||||
assert relay.relay_relevance_policy() is None
|
||||
|
||||
|
||||
def test_projection_none_when_platform_unresolved(monkeypatch):
|
||||
# Default platform "relay" ⇒ no concrete fronted platform ⇒ nothing to project.
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"discord": {"require_mention": True}},
|
||||
raising=False,
|
||||
)
|
||||
assert relay.relay_relevance_policy() is None
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# send_relay_policy() — the boot-time declaration
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
def _arm(monkeypatch, *, url="wss://connector.example/relay"):
|
||||
monkeypatch.setenv("GATEWAY_RELAY_URL", url)
|
||||
monkeypatch.setenv("GATEWAY_RELAY_ID", "gw-x")
|
||||
monkeypatch.setenv("GATEWAY_RELAY_SECRET", "s" * 48)
|
||||
monkeypatch.setenv("GATEWAY_RELAY_PLATFORM", "discord")
|
||||
|
||||
|
||||
def test_send_posts_projected_policy_with_token(monkeypatch):
|
||||
_arm(monkeypatch)
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"discord": {"require_mention": True, "free_response_channels": ["c-support"]}},
|
||||
raising=False,
|
||||
)
|
||||
captured = {}
|
||||
|
||||
def _fake_post(*, policy_url, token, policy, timeout=15.0):
|
||||
captured["policy_url"] = policy_url
|
||||
captured["token"] = token
|
||||
captured["policy"] = policy
|
||||
return 200
|
||||
|
||||
monkeypatch.setattr(relay, "_post_policy", _fake_post)
|
||||
assert relay.send_relay_policy() is True
|
||||
assert captured["policy_url"] == "https://connector.example/relay/policy"
|
||||
assert captured["token"] # a real upgrade token was minted
|
||||
assert captured["policy"]["requireAddress"] is True
|
||||
assert captured["policy"]["freeResponseScopes"] == ["c-support"]
|
||||
|
||||
|
||||
def test_send_skips_when_no_secret(monkeypatch):
|
||||
monkeypatch.setenv("GATEWAY_RELAY_URL", "wss://connector.example/relay")
|
||||
monkeypatch.setenv("GATEWAY_RELAY_PLATFORM", "discord")
|
||||
# no GATEWAY_RELAY_ID / SECRET
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"discord": {"require_mention": True}},
|
||||
raising=False,
|
||||
)
|
||||
called = {"n": 0}
|
||||
monkeypatch.setattr(relay, "_post_policy", lambda **k: called.__setitem__("n", called["n"] + 1) or 200)
|
||||
assert relay.send_relay_policy() is False
|
||||
assert called["n"] == 0 # never attempted without a secret to auth with
|
||||
|
||||
|
||||
def test_send_skips_when_nothing_to_declare(monkeypatch):
|
||||
_arm(monkeypatch)
|
||||
monkeypatch.setattr("gateway.run._load_gateway_config", lambda: {"discord": {}}, raising=False)
|
||||
called = {"n": 0}
|
||||
monkeypatch.setattr(relay, "_post_policy", lambda **k: called.__setitem__("n", called["n"] + 1) or 200)
|
||||
assert relay.send_relay_policy() is False
|
||||
assert called["n"] == 0 # no redundant write of the default
|
||||
|
||||
|
||||
def test_send_fail_soft_on_transport_error(monkeypatch):
|
||||
_arm(monkeypatch)
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"discord": {"require_mention": True}},
|
||||
raising=False,
|
||||
)
|
||||
|
||||
def _boom(**kwargs):
|
||||
raise RuntimeError("connector unreachable")
|
||||
|
||||
monkeypatch.setattr(relay, "_post_policy", _boom)
|
||||
# Never raises; returns False so boot proceeds.
|
||||
assert relay.send_relay_policy() is False
|
||||
|
||||
|
||||
def test_send_fail_soft_on_non_200(monkeypatch):
|
||||
_arm(monkeypatch)
|
||||
monkeypatch.setattr(
|
||||
"gateway.run._load_gateway_config",
|
||||
lambda: {"discord": {"require_mention": True}},
|
||||
raising=False,
|
||||
)
|
||||
monkeypatch.setattr(relay, "_post_policy", lambda **k: 401)
|
||||
assert relay.send_relay_policy() is False
|
||||
|
||||
|
||||
def test_send_skips_when_relay_unconfigured(monkeypatch):
|
||||
# No GATEWAY_RELAY_URL ⇒ relay not configured ⇒ no-op.
|
||||
monkeypatch.setattr(relay, "_post_policy", lambda **k: 200)
|
||||
assert relay.send_relay_policy() is False
|
||||
Loading…
Add table
Add a link
Reference in a new issue