adapter.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381
  1. """ntfy platform adapter: HTTP-streaming subscription (``/json``, ``poll=false``) in, POST out.
  2. config.yaml ``platforms.ntfy.extra``: ``server`` (default https://ntfy.sh), ``topic`` (required),
  3. ``publish_topic`` (defaults to topic), ``token`` (Bearer or ``user:pass`` Basic), ``markdown``
  4. (default false). Env (read at construct time; ``extra`` wins over env): NTFY_TOPIC, NTFY_SERVER_URL,
  5. NTFY_TOKEN, NTFY_PUBLISH_TOPIC, NTFY_MARKDOWN ("true"/"1"/"yes"), NTFY_ALLOWED_USERS (topic names),
  6. NTFY_ALLOW_ALL_USERS (dev only), NTFY_HOME_CHANNEL, NTFY_HOME_CHANNEL_NAME.
  7. Identity: ntfy has no authenticated user; ``title`` is publisher-controlled and NOT used for
  8. authorization. Each topic is one trusted channel (``user_id`` == topic). Protect it with a read token.
  9. """
  10. import asyncio
  11. import json
  12. import logging
  13. import time
  14. import uuid
  15. from datetime import datetime, timezone, UTC
  16. from typing import Any, Dict, List, Optional
  17. try:
  18. import httpx
  19. HTTPX_AVAILABLE = True
  20. except ImportError:
  21. HTTPX_AVAILABLE = False
  22. httpx = None # type: ignore[assignment]
  23. from gateway.config import Platform, PlatformConfig
  24. from gateway.platforms.base import BasePlatformAdapter, SendResult
  25. from gateway.platforms.event import MessageEvent, MessageType
  26. from gateway.platforms._shared import get_scoped_secret as _get_scoped_secret, send_error
  27. from gateway.platforms.helpers import MessageDeduplicator
  28. from gateway.platforms._shared import (
  29. extra_or_secret as _extra_or_secret, seed_extra_from_env as _seed_extra_from_env
  30. )
  31. from gateway.platforms.send_targets import parse_nonempty
  32. logger = logging.getLogger(__name__)
  33. class _FatalStreamError(Exception):
  34. """Unrecoverable stream error (401, 404)."""
  35. DEFAULT_SERVER = "https://ntfy.sh"
  36. MAX_MESSAGE_LENGTH = 4096 # ntfy message body limit
  37. DEDUP_WINDOW_SECONDS = 300
  38. DEDUP_MAX_SIZE = 1000
  39. RECONNECT_BACKOFF = [2, 5, 10, 30, 60]
  40. STREAM_TIMEOUT_SECONDS = 90 # ntfy keepalive default is 55s; give margin
  41. _ECHO_TAG = "hermes-agent" # tag added to outgoing messages for echo-loop prevention
  42. _MARKDOWN_TRUTHY = ("1", "true", "yes")
  43. def _build_auth_header(token: str) -> dict[str, str]:
  44. """``Authorization`` header from an ntfy token; ``{}`` when unset.
  45. Tokens are whitespace-stripped (pasted tokens often carry newlines that
  46. would malform the header). ``user:pass`` → Basic, anything else → Bearer.
  47. """
  48. token = (token or "").strip()
  49. if not token:
  50. return {}
  51. if ":" in token:
  52. import base64
  53. return {"Authorization": f"Basic {base64.b64encode(token.encode()).decode()}"}
  54. return {"Authorization": f"Bearer {token}"}
  55. def _publish_headers(token: str, markdown: bool, *, auth_first: bool = True) -> dict[str, str]:
  56. """Headers for a publish POST: auth (if any), plain-text body, echo tag, optional X-Markdown.
  57. ``auth_first`` pins the header order each call site has always sent on the wire.
  58. """
  59. auth = _build_auth_header(token)
  60. base = {"Content-Type": "text/plain; charset=utf-8", "X-Tags": _ECHO_TAG}
  61. headers = {**auth, **base} if auth_first else {**base, **auth}
  62. if markdown:
  63. headers["X-Markdown"] = "true"
  64. return headers
  65. def _truncate_body(message: str, *, context: str) -> bytes:
  66. """Apply the ntfy 4096-char limit, logging a warning (tagged ``context``) on truncation."""
  67. if len(message) > MAX_MESSAGE_LENGTH:
  68. logger.warning(
  69. "%s: truncating message from %d to %d chars (ntfy limit)",
  70. context, len(message), MAX_MESSAGE_LENGTH)
  71. return message[:MAX_MESSAGE_LENGTH].encode("utf-8")
  72. def _response_message_id(resp) -> str:
  73. """ntfy's returned message id, or a random 12-hex fallback."""
  74. try:
  75. return resp.json().get("id") or uuid.uuid4().hex[:12]
  76. except Exception:
  77. return uuid.uuid4().hex[:12]
  78. def _server_url(extra: dict[str, Any]) -> str:
  79. return _extra_or_secret(extra, "server", "NTFY_SERVER_URL", DEFAULT_SERVER).rstrip("/")
  80. def check_requirements() -> bool:
  81. """Installable and minimally configured (reads NTFY_TOPIC directly — no full config load)."""
  82. return HTTPX_AVAILABLE and bool(_get_scoped_secret("NTFY_TOPIC", "").strip())
  83. def validate_config(config) -> bool:
  84. """True when a topic is configured (config.yaml ``extra`` or env)."""
  85. return bool(_extra_or_secret(getattr(config, "extra", {}) or {}, "topic", "NTFY_TOPIC"))
  86. def is_connected(config) -> bool:
  87. """Check whether ntfy is configured (env or config.yaml)."""
  88. return bool(_get_scoped_secret("NTFY_TOPIC") or (getattr(config, "extra", {}) or {}).get("topic", ""))
  89. class NtfyAdapter(BasePlatformAdapter):
  90. """ntfy adapter: HTTP-streaming subscription in, HTTP POST publish out."""
  91. MAX_MESSAGE_LENGTH = MAX_MESSAGE_LENGTH
  92. serial_receive_loop = True # the stream loop awaits each message before reading the next line
  93. def __init__(self, config: PlatformConfig):
  94. super().__init__(config=config, platform=Platform("ntfy"))
  95. extra = config.extra or {}
  96. self._server: str = _server_url(extra)
  97. self._topic: str = _extra_or_secret(extra, "topic", "NTFY_TOPIC")
  98. self._publish_topic: str = _extra_or_secret(extra, "publish_topic", "NTFY_PUBLISH_TOPIC") or self._topic
  99. self._token: str = _extra_or_secret(extra, "token", "NTFY_TOKEN")
  100. self._stream_task: Optional[asyncio.Task] = None
  101. self._http_client: Optional[httpx.AsyncClient] = None
  102. self._dedup = MessageDeduplicator(max_size=DEDUP_MAX_SIZE, ttl_seconds=DEDUP_WINDOW_SECONDS)
  103. # -- Connection lifecycle -----------------------------------------------
  104. async def connect(self, *, is_reconnect: bool = False) -> bool:
  105. """Connect to ntfy by starting the streaming subscription task."""
  106. if not HTTPX_AVAILABLE:
  107. logger.warning("[%s] httpx not installed. Run: pip install httpx", self.name)
  108. return False
  109. if not self._topic:
  110. logger.warning("[%s] NTFY_TOPIC not configured", self.name)
  111. return False
  112. try:
  113. self._http_client = httpx.AsyncClient(timeout=None)
  114. self._stream_task = asyncio.create_task(self._run_stream())
  115. self._mark_connected()
  116. logger.info("[%s] Connected — subscribing to %s/%s", self.name, self._server, self._topic)
  117. self._wire_plugin_handlers(None)
  118. return True
  119. except Exception as e:
  120. logger.error("[%s] Failed to connect: %s", self.name, e)
  121. return False
  122. async def _run_stream(self) -> None:
  123. """Subscribe to the ntfy topic with automatic reconnection."""
  124. backoff_idx = 0
  125. stream_start: float = 0.0
  126. url = f"{self._server}/{self._topic}/json"
  127. headers = self._auth_headers()
  128. while self._running:
  129. try:
  130. logger.debug("[%s] Opening stream to %s", self.name, url)
  131. stream_start = time.monotonic()
  132. await self._consume_stream(url, headers)
  133. except asyncio.CancelledError:
  134. return
  135. except _FatalStreamError:
  136. self._running = False
  137. return
  138. except Exception as e:
  139. if not self._running:
  140. return
  141. logger.warning("[%s] Stream error: %s", self.name, e)
  142. if not self._running:
  143. return
  144. # Reset backoff if stream stayed alive for at least 60s
  145. if time.monotonic() - stream_start >= 60.0:
  146. backoff_idx = 0
  147. delay = RECONNECT_BACKOFF[min(backoff_idx, len(RECONNECT_BACKOFF) - 1)]
  148. logger.info("[%s] Reconnecting in %ds...", self.name, delay)
  149. await asyncio.sleep(delay)
  150. backoff_idx += 1
  151. def _fatal_status(self, status_code: int) -> None:
  152. """401/404 are unrecoverable: log, set the fatal state and raise ``_FatalStreamError``."""
  153. if status_code == 401:
  154. logger.error(
  155. "[%s] Authentication failed (401) — stopping reconnect loop. Check NTFY_TOKEN.", self.name)
  156. code, detail = "ntfy_unauthorized", "ntfy server rejected auth (401). Check NTFY_TOKEN."
  157. reason = "401 Unauthorized"
  158. elif status_code == 404:
  159. logger.error("[%s] Topic not found (404): %s — stopping reconnect loop.", self.name, self._topic)
  160. code, detail = "ntfy_topic_not_found", f"ntfy topic '{self._topic}' returned 404. Check NTFY_TOPIC."
  161. reason = "404 Not Found"
  162. else:
  163. return
  164. self._set_fatal_error(code, detail, retryable=False)
  165. raise _FatalStreamError(reason)
  166. async def _consume_stream(self, url: str, headers: dict[str, str]) -> None:
  167. """Open an HTTP streaming connection and dispatch events."""
  168. # poll=false keeps a persistent streaming connection alive with keepalive events
  169. async with self._http_client.stream(
  170. "GET", url, headers=headers, params={"poll": "false"},
  171. timeout=httpx.Timeout(connect=15.0, read=STREAM_TIMEOUT_SECONDS, write=15.0, pool=15.0),
  172. ) as response:
  173. self._fatal_status(response.status_code)
  174. response.raise_for_status()
  175. async for line in response.aiter_lines():
  176. if not self._running:
  177. return
  178. line = line.strip()
  179. if not line:
  180. continue
  181. try:
  182. event = json.loads(line)
  183. except json.JSONDecodeError:
  184. continue
  185. if event.get("event") == "message":
  186. await self._on_message(event)
  187. async def disconnect(self) -> None:
  188. """Disconnect from ntfy."""
  189. self._running = False
  190. self._mark_disconnected()
  191. if self._stream_task:
  192. self._stream_task.cancel()
  193. try:
  194. await self._stream_task
  195. except asyncio.CancelledError:
  196. pass
  197. self._stream_task = None
  198. if self._http_client:
  199. await self._http_client.aclose()
  200. self._http_client = None
  201. self._dedup.clear()
  202. logger.info("[%s] Disconnected", self.name)
  203. # -- Inbound message processing -----------------------------------------
  204. async def _on_message(self, event: dict[str, Any]) -> None:
  205. """Process an incoming ntfy message event."""
  206. msg_id = event.get("id") or uuid.uuid4().hex
  207. if self._dedup.is_duplicate(msg_id):
  208. logger.debug("[%s] Duplicate message %s, skipping", self.name, msg_id)
  209. return
  210. if _ECHO_TAG in (event.get("tags") or []):
  211. logger.debug("[%s] Skipping own message (echo tag)", self.name)
  212. return
  213. text = (event.get("message") or "").strip()
  214. if not text:
  215. logger.debug("[%s] Empty message body, skipping", self.name)
  216. return
  217. # No native user identity on ntfy: the publisher-controlled title must
  218. # NOT drive authorization, so user_id is fixed to the topic name.
  219. topic = event.get("topic") or self._topic
  220. source = self.build_source(
  221. chat_id=topic, chat_name=topic, chat_type="dm", user_id=topic, user_name=topic, message_id=msg_id)
  222. unix_ts, timestamp = event.get("time"), datetime.now(tz=UTC)
  223. try:
  224. timestamp = datetime.fromtimestamp(int(unix_ts), tz=UTC) if unix_ts else timestamp
  225. except (ValueError, OSError, TypeError):
  226. pass
  227. message_event = MessageEvent(
  228. text=text, message_type=MessageType.TEXT, source=source, message_id=msg_id,
  229. raw_message=event, timestamp=timestamp)
  230. logger.debug("[%s] Message on topic %s: %s", self.name, topic, text[:80])
  231. await self.handle_message(message_event)
  232. # -- Outbound messaging -------------------------------------------------
  233. async def send(
  234. self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  235. ) -> SendResult:
  236. """Publish a message to the configured publish topic."""
  237. publish_topic = (metadata or {}).get("publish_topic") or self._publish_topic or chat_id
  238. if not self._http_client:
  239. return SendResult(success=False, error="HTTP client not initialized")
  240. headers = _publish_headers(self._token, bool((self.config.extra or {}).get("markdown", False)))
  241. if len(content) > self.MAX_MESSAGE_LENGTH:
  242. logger.warning(
  243. "[%s] Message truncated from %d to %d chars (ntfy limit)",
  244. self.name, len(content), self.MAX_MESSAGE_LENGTH)
  245. body = content[:self.MAX_MESSAGE_LENGTH].encode("utf-8")
  246. try:
  247. resp = await self._http_client.post(
  248. f"{self._server}/{publish_topic}", content=body, headers=headers, timeout=15.0)
  249. if resp.status_code < 300:
  250. return SendResult(success=True, message_id=_response_message_id(resp))
  251. body_text = resp.text
  252. logger.warning("[%s] Send failed HTTP %d: %s", self.name, resp.status_code, body_text[:200])
  253. return SendResult(success=False, error=f"HTTP {resp.status_code}: {body_text[:200]}")
  254. except httpx.TimeoutException:
  255. return SendResult(success=False, error="Timeout publishing to ntfy")
  256. except Exception as e:
  257. logger.error("[%s] Send error: %s", self.name, e)
  258. return SendResult(success=False, error=str(e))
  259. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  260. return {"name": chat_id, "type": "dm"}
  261. def _auth_headers(self) -> dict[str, str]:
  262. return _build_auth_header(self._token)
  263. # -- Plugin registration -----------------------------------------------------
  264. def _env_enablement() -> dict | None:
  265. """``env_enablement_fn``: seed ``PlatformConfig.extra`` from the profile's env before adapter
  266. construction; ``None`` when ``NTFY_TOPIC`` is unset."""
  267. topic = _get_scoped_secret("NTFY_TOPIC", "").strip()
  268. if not topic:
  269. return None
  270. seed = _seed_extra_from_env((
  271. ("NTFY_SERVER_URL", "server", lambda v: v.rstrip("/")), ("NTFY_PUBLISH_TOPIC", "publish_topic", None),
  272. ("NTFY_TOKEN", "token", None), ("NTFY_MARKDOWN", "markdown", lambda v: v.lower() in _MARKDOWN_TRUTHY),
  273. ), home_env="NTFY_HOME_CHANNEL", home_default=topic)
  274. return {"topic": topic, "server": seed.pop("server", DEFAULT_SERVER), **seed}
  275. async def _standalone_send(
  276. pconfig, chat_id: str, message: str, *,
  277. thread_id: Optional[str] = None, media_files: Optional[list[str]] = None, force_document: bool = False,
  278. ) -> dict[str, Any]:
  279. """Out-of-process publish for cron / send_message_tool when no gateway adapter is live.
  280. ``thread_id``/``media_files`` are signature parity only (ntfy has no thread
  281. or attachment primitive). Markdown is honored if ``NTFY_MARKDOWN`` is set
  282. OR ``pconfig.extra["markdown"]`` is True.
  283. """
  284. if not HTTPX_AVAILABLE:
  285. return send_error("ntfy standalone send: httpx not installed")
  286. extra = getattr(pconfig, "extra", {}) or {}
  287. server = _server_url(extra)
  288. publish_topic = (
  289. chat_id or extra.get("publish_topic") or _get_scoped_secret("NTFY_PUBLISH_TOPIC", "").strip()
  290. or extra.get("topic") or _get_scoped_secret("NTFY_TOPIC", "").strip())
  291. if not publish_topic:
  292. return send_error("ntfy standalone send: NTFY_TOPIC not configured")
  293. token = _extra_or_secret(extra, "token", "NTFY_TOKEN")
  294. markdown_env = _get_scoped_secret("NTFY_MARKDOWN", "").strip().lower()
  295. markdown = bool(extra.get("markdown")) or markdown_env in _MARKDOWN_TRUTHY
  296. headers = _publish_headers(token, markdown, auth_first=False)
  297. body = _truncate_body(message, context="ntfy standalone")
  298. try:
  299. async with httpx.AsyncClient(timeout=15.0) as client:
  300. resp = await client.post(f"{server}/{publish_topic}", content=body, headers=headers)
  301. if resp.status_code >= 300:
  302. return send_error(f"ntfy HTTP {resp.status_code}: {resp.text[:200]}")
  303. return {"success": True, "platform": "ntfy", "chat_id": publish_topic, "message_id": _response_message_id(resp)}
  304. except Exception as e:
  305. return send_error(f"ntfy standalone send failed: {e}")
  306. def register(ctx) -> None:
  307. """Plugin entry point — called by the Hermes plugin system at startup."""
  308. ctx.register_platform(
  309. target_ref_syntax_fn=parse_nonempty,
  310. name="ntfy", label="ntfy", adapter_factory=lambda cfg: NtfyAdapter(cfg),
  311. dashboard_description="Chat with Hermes over ntfy push topics (ntfy.sh or self-hosted).",
  312. docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/messaging/ntfy",
  313. check_fn=check_requirements, validate_config=validate_config, is_connected=is_connected,
  314. required_env=["NTFY_TOPIC"], install_hint="pip install httpx # already a Hermes dependency",
  315. env_enablement_fn=_env_enablement, # env-only setups show in `gateway status`
  316. cron_deliver_env_var="NTFY_HOME_CHANNEL",
  317. standalone_sender_fn=_standalone_send, # out-of-process cron delivery
  318. allowed_users_env="NTFY_ALLOWED_USERS", allow_all_env="NTFY_ALLOW_ALL_USERS",
  319. max_message_length=MAX_MESSAGE_LENGTH, emoji="🔔",
  320. pii_safe=True, # topic names only — no phone numbers / emails to redact
  321. allow_update_command=True,
  322. platform_hint=(
  323. "You are communicating via ntfy push notifications. "
  324. "Use plain text by default — ntfy supports optional markdown "
  325. "(set markdown: true in config or NTFY_MARKDOWN=true). "
  326. "Keep responses concise; ntfy is a push notification service "
  327. "with a 4096-character per-message limit."
  328. ))