feat(channels): add NATS channel (request/reply front-end)

- NatsChannel: subscribe in_subject (agenthub.in.>), publish replies to
  out_subject.<chat_id>; JSON bodies {chat_id, user_id?, text}
- deltas dropped (no edit semantics), final/status/interaction/command
  rendered via shared base helpers; allowed_users gate; 900KB split
- vendored SyncNATS wrapper (nats-py is asyncio-only; thread behind)
- runtime.build_channels wiring; optional dependency extra "nats"
- 9 mock-transport tests; full suite 116 passed
This commit is contained in:
openbot committed 2026-10-16 11:04:02 +08:00
1 parent ee1cca839f
commit f688e3be9f
4 files changed
+559

No files matched your search

+249
View File
@@ -0,0 +1,249 @@
"""Synchronous wrapper over nats-py.
nats-py is asyncio-only (no official sync client exists). This module runs
the entire client on a dedicated background event-loop thread and exposes
blocking, thread-safe calls: the same pub/sub semantics as ``nats.connect``
without requiring the caller to have an event loop.
Not affiliated with nats-py; requires ``nats-py>=2.6.0`` to be installed.
"""
from __future__ import annotations
import asyncio
import threading
from typing import Any, Callable
__all__ = ["SyncNATS", "SyncMsg"]
ConnectCallback = Callable[[], None]
MessageCallback = Callable[["SyncMsg"], None]
class SyncMsg:
"""A received message. ``data`` is raw bytes, ``subject`` the topic."""
__slots__ = ("subject", "data", "reply", "_ack")
def __init__(self, subject: str, data: bytes, reply: str = "") -> None:
self.subject = subject
self.data = data
self.reply = reply
def decode(self) -> str:
return self.data.decode("utf-8", errors="replace")
def __repr__(self) -> str: # pragma: no cover
return f"<SyncMsg subject={self.subject!r} {len(self.data)} bytes>"
class SyncNATS:
"""Blocking NATS client. Create one per process (or per connection).
Example:
nc = SyncNATS("nats://localhost:4222")
nc.subscribe("bots.*.in", callback=lambda m: print(m.decode()))
nc.publish("bots.x.out", b"hello")
nc.close()
"""
def __init__(
self,
servers: str = "nats://localhost:4222",
*,
username: str = "",
password: str = "",
connect_timeout: float = 10.0,
on_connect: ConnectCallback | None = None,
on_disconnect: ConnectCallback | None = None,
) -> None:
self._servers = servers
self._username = username
self._password = password
self._connect_timeout = connect_timeout
self._on_connect = on_connect
self._on_disconnect = on_disconnect
self._ready = threading.Event()
self._connect_error: BaseException | None = None
self._loop = asyncio.new_event_loop()
self._thread = threading.Thread(
target=self._thread_main, name="sync-nats", daemon=True
)
self._thread.start()
# Wait for connect to finish (success or failure) before returning.
self._ready.wait(timeout=self._connect_timeout + 5)
if self._connect_error is not None:
self._shutdown_loop()
raise self._connect_error
# ------------------------------------------------------------------
# Background loop thread
# ------------------------------------------------------------------
def _thread_main(self) -> None:
asyncio.set_event_loop(self._loop)
self._loop.run_until_complete(self._connect())
self._loop.run_forever()
# Loop stopped: drain remaining callbacks then close.
pending = asyncio.all_tasks(self._loop)
if pending:
self._loop.run_until_complete(
asyncio.gather(*pending, return_exceptions=True)
)
self._loop.close()
async def _connect(self) -> None:
import nats
servers = [s.strip() for s in self._servers.split(",") if s.strip()]
async def _disc() -> None:
if self._on_disconnect:
try:
self._on_disconnect()
except Exception:
pass
async def _reconn() -> None:
if self._on_connect:
try:
self._on_connect()
except Exception:
pass
try:
self._nc = await nats.connect(
servers=servers,
user=self._username or None,
password=self._password or None,
connect_timeout=int(self._connect_timeout),
reconnect_time_wait=1,
max_reconnect_attempts=-1,
disconnected_cb=_disc,
reconnected_cb=_reconn,
)
except BaseException as exc: # propagate to the constructing thread
self._connect_error = exc
finally:
self._ready.set()
def _shutdown_loop(self) -> None:
if self._loop.is_running():
self._loop.call_soon_threadsafe(self._loop.stop)
if self._thread.is_alive():
self._thread.join(timeout=5)
# ------------------------------------------------------------------
# Public blocking API
# ------------------------------------------------------------------
def publish(self, subject: str, data: bytes | str) -> None:
"""Publish and flush before returning (send-and-forget semantics)."""
if isinstance(data, str):
data = data.encode("utf-8")
done = threading.Event()
err: list[BaseException] = []
async def _pub() -> None:
try:
await self._nc.publish(subject, data)
await self._nc.flush()
except BaseException as exc:
err.append(exc)
finally:
done.set()
self._loop.call_soon_threadsafe(self._loop.create_task, _pub())
if not done.wait(timeout=30):
raise TimeoutError(f"publish timed out to {subject}")
if err:
raise err[0]
def subscribe(self, subject: str, callback: MessageCallback) -> str:
"""Subscribe with a sync callback invoked on the NATS thread."""
done = threading.Event()
err: list[BaseException] = []
sid_box: list[str] = []
async def _sub() -> None:
try:
sub = await self._nc.subscribe(subject, cb=self._make_cb(callback))
sid_box.append(str(sub._id))
except BaseException as exc:
err.append(exc)
finally:
done.set()
self._loop.call_soon_threadsafe(self._loop.create_task, _sub())
if not done.wait(timeout=10):
raise TimeoutError(f"subscribe timed out for {subject}")
if err:
raise err[0]
return sid_box[0]
def unsubscribe(self, sid: str) -> None:
done = threading.Event()
async def _unsub() -> None:
try:
sub = self._nc._subs.get(int(sid))
if sub is not None:
await sub.unsubscribe()
finally:
done.set()
self._loop.call_soon_threadsafe(self._loop.create_task, _unsub())
done.wait(timeout=10)
def request(self, subject: str, data: bytes | str, timeout: float = 5.0) -> SyncMsg:
"""Blocking request/reply using nats-py's inbox machinery."""
if isinstance(data, str):
data = data.encode("utf-8")
fut: asyncio.Future = self._loop.create_future()
async def _req() -> None:
try:
msg = await self._nc.request(subject, data, timeout=timeout)
if not fut.done():
fut.set_result(msg)
except BaseException as exc:
if not fut.done():
fut.set_exception(exc)
self._loop.call_soon_threadsafe(self._loop.create_task, _req())
msg = fut.result(timeout=timeout + 5) # may raise TimeoutError / Error
return SyncMsg(msg.subject, msg.data, msg.reply or "")
def is_connected(self) -> bool:
return self._nc is not None and self._nc.is_connected
def close(self) -> None:
"""Flush pending publishes and stop the background thread."""
if getattr(self, "_nc", None) is not None:
nc, self._nc = self._nc, None
fut = asyncio.run_coroutine_threadsafe(nc.drain(), self._loop)
try:
fut.result(timeout=5)
except Exception:
pass
self._shutdown_loop()
# ------------------------------------------------------------------
def _make_cb(self, user_cb: MessageCallback) -> Callable:
async def _cb(msg: Any) -> None:
sync_msg = SyncMsg(msg.subject, msg.data, msg.reply or "")
# Run the user callback off the loop thread (it may block).
await asyncio.get_running_loop().run_in_executor(None, user_cb, sync_msg)
return _cb
def __enter__(self) -> "SyncNATS":
return self
def __exit__(self, *exc: Any) -> None:
self.close()
+168
View File
@@ -0,0 +1,168 @@
"""NATS channel for agenthub: request/reply over NATS subjects.
M1 channel. NATS is a peer front-end (same IMChannel contract as wecom/
weixin); agenthub is a NATS client. Protocol:
- inbound: subscribe to ``subject_prefix`` (default ``agenthub.in.>``).
Message body = JSON {"chat_id", "user_id"?, "text"} (extra fields kept
in raw). If the message carries a ``reply`` subject, final answers are
published back to it; otherwise to ``subject_prefix`` with ``.out``
semantics (see below).
- outbound: reply(chat_id, text) publishes JSON {"chat_id", "text"} to
``out_subject`` (default ``agenthub.out.<chat_id>``).
Channel name is "nats"; chat keys become "nats:<chat_id>" downstream.
Config (dict):
servers: str = "nats://localhost:4222" # comma separated
username / password: str = ""
in_subject: str = "agenthub.in.>" # subscription pattern
out_subject: str = "agenthub.out" # replies published to out_subject.<chat_id>
allowed_users: list[str] = []
Requires the ``nats`` extra (nats-py). Reuses octop-gateway's SyncNATS
wrapper (vendored copy, asyncio-only nats-py behind a thread).
"""
from __future__ import annotations
import json
import logging
import threading
from typing import Any, Callable
from .base import (
IMChannel,
InboundMessage,
_command_result_text,
_interaction_text,
clean_control_chars,
split_message_text,
)
log = logging.getLogger("agenthub.nats")
MAX_TEXT_BYTES = 900_000 # NATS default max_payload is 1MB; stay under it
def _log():
return logging.getLogger("agenthub.nats")
class NatsChannel:
name = "nats"
def __init__(
self,
config: dict[str, Any],
nats_factory: Callable[..., Any] | None = None,
logger: Any = None,
):
self.servers = (config.get("servers") or "nats://localhost:4222").strip()
self.username = config.get("username", "")
self.password = config.get("password", "")
self.in_subject = config.get("in_subject", "agenthub.in.>")
self.out_subject = (config.get("out_subject") or "agenthub.out").rstrip(".")
self.allowed_users = set(config.get("allowed_users") or [])
self._nats_factory = nats_factory # injectable for tests
self._nc: Any = None
self._sub_id: str | None = None
self._msg_cb: Callable[[InboundMessage], None] | None = None
self._sink: Callable[[str, str, dict], None] | None = None
self._logger = logger or _log()
self._stop = threading.Event()
# -- IMChannel ---------------------------------------------------------
def start(self) -> None:
from ._nats_sync import SyncNATS # vendored sync wrapper
factory = self._nats_factory or SyncNATS
self._nc = factory(
self.servers,
username=self.username,
password=self.password,
on_connect=lambda: self._logger.info("[nats] connected"),
on_disconnect=lambda: self._logger.warning("[nats] disconnected; reconnecting"),
)
self._sub_id = self._nc.subscribe(self.in_subject, self._on_nats_msg)
self._logger.info(f"[nats] subscribed {self.in_subject} (out: {self.out_subject}.*)")
def stop(self) -> None:
self._stop.set()
if self._nc:
try:
if self._sub_id:
self._nc.unsubscribe(self._sub_id)
self._nc.close()
except Exception as e: # noqa: BLE001
self._logger.warning(f"[nats] close error: {e}")
self._nc = None
def on_message(self, cb: Callable[[InboundMessage], None]) -> None:
self._msg_cb = cb
def set_event_sink(self, sink: Callable[[str, str, dict], None]) -> None:
self._sink = sink
# -- inbound -----------------------------------------------------------
def _on_nats_msg(self, msg: Any) -> None:
"""NATS thread callback — must never raise (sync wrapper logs)."""
try:
data = json.loads(msg.decode())
chat_id = str(data.get("chat_id") or "").strip()
if not chat_id:
# fall back to the subject's last token as chat id
chat_id = msg.subject.rsplit(".", 1)[-1]
user_id = str(data.get("user_id") or chat_id)
if self.allowed_users and user_id not in self.allowed_users:
self._logger.warning(f"[nats] user {user_id!r} not allowed; drop")
return
text = clean_control_chars(str(data.get("text") or ""), max_len=100_000).strip()
if not text:
return
if self._msg_cb:
self._msg_cb(
InboundMessage(
channel=self.name,
chat_id=chat_id,
user_id=user_id,
text=text,
raw={"subject": msg.subject, "reply": msg.reply or ""},
)
)
except Exception as e: # noqa: BLE001 — never kill the subscription
self._logger.error(f"[nats] inbound dispatch failed: {e}")
# -- outbound ----------------------------------------------------------
def _publish_out(self, chat_id: str, payload: dict[str, Any]) -> None:
if not self._nc:
return
subject = f"{self.out_subject}.{chat_id}"
body = json.dumps(payload, ensure_ascii=False).encode()
if len(body) > MAX_TEXT_BYTES:
self._logger.warning(f"[nats] payload {len(body)}B > {MAX_TEXT_BYTES}B; dropping")
return
try:
self._nc.publish(subject, body)
except Exception as e: # noqa: BLE001
self._logger.error(f"[nats] publish to {subject} failed: {e}")
def reply(self, chat_id: str, text: str) -> None:
# split under the per-message byte budget (envelope counts too)
budget = MAX_TEXT_BYTES - 200
for chunk in split_message_text(text, budget):
self._publish_out(chat_id, {"chat_id": chat_id, "text": chunk})
def push_event(self, chat_id: str, kind: str, payload: dict[str, Any]) -> None:
if kind == "delta":
# NATS has no edit semantics; stream deltas as status lines is
# noise — accumulate and deliver on final only.
return
if kind == "final":
self.reply(chat_id, str(payload.get("text", "")))
elif kind == "status":
self._publish_out(chat_id, {"chat_id": chat_id, "status": str(payload.get("text", ""))})
elif kind in ("interaction", "permission"):
self.reply(chat_id, _interaction_text(payload))
elif kind == "command_result":
self.reply(chat_id, _command_result_text(payload))
+4
View File
@@ -84,6 +84,10 @@ def build_channels(cfg: dict[str, Any], mgr: SessionManager) -> list:
sink_and_inbound(WecomAppChannel(ccfg["wecom-app"]))
if "weixin" in ccfg:
sink_and_inbound(WeixinChannel(ccfg["weixin"]))
if "nats" in ccfg:
from .channels.nats import NatsChannel
sink_and_inbound(NatsChannel(ccfg["nats"]))
# ONE dispatch-all event sink (per-channel sinks would overwrite each
# other; _safe_event filters per channel name anyway). Approvals
+138
View File
@@ -0,0 +1,138 @@
"""Tests for the NATS channel (mocked transport, no network)."""
from __future__ import annotations
import json
from typing import Any
import pytest
from agenthub.channels.nats import NatsChannel
from agenthub.channels.base import InboundMessage
class FakeMsg:
def __init__(self, subject: str, data: bytes, reply: str = ""):
self.subject = subject
self.data = data
self.reply = reply
def decode(self) -> str:
return self.data.decode()
class FakeNATS:
"""Minimal SyncNATS stand-in: records subs/pubs, replays on demand."""
def __init__(self, *a, **kw):
self.subs: dict[str, Any] = {}
self.pubs: list[tuple[str, bytes]] = []
self.closed = False
def subscribe(self, subject, cb):
self.subs[subject] = cb
return f"sid-{len(self.subs)}"
def unsubscribe(self, sid):
pass
def publish(self, subject, data):
self.pubs.append((subject, data))
def close(self):
self.closed = True
@pytest.fixture()
def ch_and_nc():
nc = FakeNATS()
ch = NatsChannel({"servers": "nats://x:4222"}, nats_factory=lambda *a, **kw: nc)
inbound: list[InboundMessage] = []
ch.on_message(inbound.append)
ch.start()
yield ch, nc, inbound
ch.stop()
def _feed(nc: FakeNATS, subject: str, payload: dict, reply: str = ""):
cb = next(iter(nc.subs.values()))
cb(FakeMsg(subject, json.dumps(payload).encode(), reply))
def test_start_subscribes_and_stop_closes(ch_and_nc):
ch, nc, _ = ch_and_nc
assert "agenthub.in.>" in nc.subs
ch.stop()
assert nc.closed
def test_inbound_message_dispatch(ch_and_nc):
ch, nc, inbound = ch_and_nc
_feed(nc, "agenthub.in.chat1", {"chat_id": "chat1", "user_id": "u1", "text": "hello"})
assert len(inbound) == 1
m = inbound[0]
assert m.channel == "nats"
assert m.chat_id == "chat1"
assert m.user_id == "u1"
assert m.text == "hello"
assert m.raw["subject"] == "agenthub.in.chat1"
def test_inbound_chat_id_falls_back_to_subject(ch_and_nc):
ch, nc, inbound = ch_and_nc
_feed(nc, "agenthub.in.room9", {"text": "hi"})
assert inbound[0].chat_id == "room9"
assert inbound[0].user_id == "room9"
def test_inbound_allowed_users_gate(ch_and_nc):
ch, nc, inbound = ch_and_nc
ch.allowed_users = {"alice"}
_feed(nc, "agenthub.in.c1", {"chat_id": "c1", "user_id": "bob", "text": "x"})
assert inbound == []
_feed(nc, "agenthub.in.c1", {"chat_id": "c1", "user_id": "alice", "text": "x"})
assert len(inbound) == 1
def test_inbound_bad_json_does_not_raise(ch_and_nc):
ch, nc, inbound = ch_and_nc
cb = next(iter(nc.subs.values()))
cb(FakeMsg("agenthub.in.c1", b"not json"))
cb(FakeMsg("agenthub.in.c1", json.dumps({"text": " "}).encode())) # empty text
assert inbound == []
def test_final_event_publishes_to_out_subject(ch_and_nc):
ch, nc, _ = ch_and_nc
ch.push_event("chat1", "final", {"text": "answer"})
assert nc.pubs == [("agenthub.out.chat1", json.dumps({"chat_id": "chat1", "text": "answer"}, ensure_ascii=False).encode())]
def test_delta_dropped_status_published(ch_and_nc):
ch, nc, _ = ch_and_nc
ch.push_event("c", "delta", {"text": "partial"})
assert nc.pubs == []
ch.push_event("c", "status", {"text": "running..."})
assert nc.pubs[0][0] == "agenthub.out.c"
assert b"running..." in nc.pubs[0][1]
def test_interaction_renders_numbered_options(ch_and_nc):
ch, nc, _ = ch_and_nc
ch.push_event("c", "interaction", {
"interaction_type": "permission", "tool": "execute",
"options": [{"option_id": "allow", "name": "Allow once", "kind": "allow_once"}],
"request_id": "req-1",
})
subject, body = nc.pubs[0]
assert subject == "agenthub.out.c"
text = json.loads(body)["text"]
assert "execute" in text and "Allow once" in text and "req-1" in text
def test_reply_splits_long_text(ch_and_nc):
ch, nc, _ = ch_and_nc
ch.reply("c", "x" * 1_200_000) # > 900k budget -> 2 chunks
assert len(nc.pubs) == 2
total = sum(len(json.loads(b)["text"]) for _, b in nc.pubs)
assert total >= 1_199_000