adapter.py 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764
  1. """Mattermost gateway adapter — REST API v4 + WebSocket via aiohttp (no Mattermost SDK).
  2. Environment variables:
  3. MATTERMOST_URL Server URL (e.g. https://mm.example.com)
  4. MATTERMOST_TOKEN Bot token or personal-access token
  5. MATTERMOST_ALLOWED_USERS Comma-separated user IDs
  6. MATTERMOST_HOME_CHANNEL Channel ID for cron/notification delivery
  7. """
  8. from __future__ import annotations
  9. import asyncio
  10. import json
  11. import logging
  12. import mimetypes
  13. import os
  14. import re
  15. from pathlib import Path
  16. from urllib.parse import unquote as _unquote
  17. from typing import Any, Dict, List, Optional, Tuple
  18. from gateway.config import Platform, PlatformConfig
  19. from gateway.platforms.helpers import MessageDeduplicator
  20. from gateway.platforms.helpers import cancel_task
  21. from gateway.platforms.base import gateway_trust_env, BasePlatformAdapter, SendResult
  22. from gateway.platforms.event import MessageEvent, MessageType
  23. from gateway.platforms._shared import (
  24. apply_yaml_bridge as _apply_yaml_bridge, env_is_connected as _env_is_connected,
  25. extra_or_secret as _extra_or_secret, get_scoped_secret as _get_scoped_secret,
  26. send_error
  27. )
  28. logger = logging.getLogger(__name__)
  29. _Metadata = Optional[dict[str, Any]]
  30. # Server default is 16383, but 4000 is the practical limit for readable messages.
  31. MAX_POST_LENGTH = 4000
  32. # Channel type codes returned by the Mattermost API ("P" private → treat as group).
  33. _CHANNEL_TYPE_MAP = {"D": "dm", "G": "group", "P": "group", "O": "channel"}
  34. _MATTERMOST_DISABLE_MENTIONS_PROPS = {"disable_mentions": True}
  35. _RECONNECT_BASE_DELAY, _RECONNECT_MAX_DELAY, _RECONNECT_JITTER = 2.0, 60.0, 0.2 # exponential backoff
  36. _POST_WITH_FILE_ERROR = "Failed to post with file"
  37. _MEDIA_MSG_TYPES = (("image/", MessageType.PHOTO), ("audio/", MessageType.VOICE)) # first match wins
  38. _INBOUND_CACHE_EXT = {"image/": ".png", "audio/": ".ogg"} # mime prefix → default extension for cached media
  39. def _with_mentions_disabled(payload: dict[str, Any]) -> dict[str, Any]:
  40. """Return a post payload that prevents Mattermost from firing mentions."""
  41. props, disable = payload.get("props"), _MATTERMOST_DISABLE_MENTIONS_PROPS
  42. payload["props"] = {**props, **disable} if isinstance(props, dict) else dict(disable)
  43. return payload
  44. def _channel_id_set(raw: Any) -> set:
  45. """Parse a list or comma-separated string of channel IDs into a stripped set."""
  46. items = raw if isinstance(raw, list) else str(raw).split(",")
  47. return {str(c).strip() for c in items if str(c).strip()}
  48. def _post_result(data: dict[str, Any], error: str) -> SendResult:
  49. if not data or "id" not in data:
  50. return SendResult(success=False, error=error)
  51. return SendResult(success=True, message_id=data["id"])
  52. def _url_filename(url: str, fallback: str) -> str:
  53. return url.rsplit("/", 1)[-1].split("?")[0] or fallback
  54. def _url_and_token(config) -> tuple[str, str]:
  55. """(server URL, token): ``config`` first, MATTERMOST_URL / MATTERMOST_TOKEN env fallback."""
  56. extra = getattr(config, "extra", {}) or {}
  57. return (extra.get("url") or _get_scoped_secret("MATTERMOST_URL", ""),
  58. getattr(config, "token", None) or _get_scoped_secret("MATTERMOST_TOKEN", ""))
  59. def check_mattermost_requirements() -> bool:
  60. """Return True if the Mattermost adapter runtime dependency is available."""
  61. try:
  62. import aiohttp
  63. return True
  64. except ImportError:
  65. logger.warning("Mattermost: aiohttp not installed")
  66. return False
  67. def validate_mattermost_config(config: PlatformConfig) -> bool:
  68. """Return True when Mattermost has enough config to connect."""
  69. url, token = _url_and_token(config)
  70. if not token.strip():
  71. logger.debug("Mattermost: MATTERMOST_TOKEN not set")
  72. return False
  73. if not url.strip():
  74. logger.warning("Mattermost: MATTERMOST_URL not set")
  75. return False
  76. return True
  77. class MattermostAdapter(BasePlatformAdapter):
  78. """Gateway adapter for Mattermost (self-hosted or cloud)."""
  79. splits_long_messages = True # send() chunks via truncate_message(MAX_POST_LENGTH)
  80. serial_receive_loop = True # the WebSocket loop awaits each event before reading the next
  81. def __init__(self, config: PlatformConfig):
  82. super().__init__(config, Platform.MATTERMOST)
  83. self._base_url, self._token = _url_and_token(config)
  84. self._base_url = self._base_url.rstrip("/")
  85. self._bot_user_id = self._bot_username = ""
  86. self._session: Any = None # aiohttp.ClientSession
  87. self._ws: Any = None # aiohttp.ClientWebSocketResponse
  88. self._ws_task: Optional[asyncio.Task] = None
  89. self._reconnect_task: Optional[asyncio.Task] = None
  90. self._closing = False
  91. # Reply mode: "thread" to nest replies, "off" for flat messages.
  92. self._reply_mode: str = (
  93. config.extra.get("reply_mode", "") or _get_scoped_secret("MATTERMOST_REPLY_MODE", "off")).lower()
  94. self._last_post_status: Optional[int] = None # POST-only, read by the broken-thread-root fallback
  95. self._last_post_error: str = ""
  96. self._dedup = MessageDeduplicator()
  97. def _is_configured_bot_user(self, user_id: str) -> bool:
  98. """Whether an inbound Mattermost sender is an explicitly configured peer bot.
  99. Mattermost's posted WebSocket event contains only a sender ID, not a bot flag. Keep the
  100. classification opt-in: an unknown account stays a human rather than silently changing its
  101. authorization or delivery behavior. ``bot_users`` in config.yaml is read by the base
  102. ``build_source``; ``MATTERMOST_BOT_USERS`` is its env spelling.
  103. """
  104. return str(user_id) in _channel_id_set(_get_scoped_secret("MATTERMOST_BOT_USERS", ""))
  105. # --- HTTP helpers ---
  106. def _headers(self) -> dict[str, str]:
  107. return {**self._auth_header(), "Content-Type": "application/json"}
  108. def _auth_header(self) -> dict[str, str]:
  109. return {"Authorization": f"Bearer {self._token}"}
  110. async def _api(self, method: str, path: str, payload: Optional[dict[str, Any]] = None) -> dict[str, Any]:
  111. """{method} /api/v4/{path}; POST also records _last_post_status/_last_post_error."""
  112. import aiohttp
  113. if ".." in path:
  114. logger.error("MM API path traversal blocked: %s", path)
  115. return {}
  116. url = f"{self._base_url}/api/v4/{path.lstrip('/')}"
  117. is_post = method == "POST"
  118. if is_post:
  119. self._last_post_status, self._last_post_error = None, ""
  120. kwargs: dict[str, Any] = {"headers": self._headers()}
  121. if payload is not None:
  122. kwargs["json"] = payload
  123. if method != "PUT": # PUT relies on the session default timeout
  124. kwargs["timeout"] = aiohttp.ClientTimeout(total=30)
  125. try:
  126. async with getattr(self._session, method.lower())(url, **kwargs) as resp:
  127. if is_post:
  128. self._last_post_status = resp.status
  129. if resp.status >= 400:
  130. body = await resp.text()
  131. if is_post:
  132. self._last_post_error = body or ""
  133. logger.error("MM API %s %s → %s: %s", method, path, resp.status, body[:200])
  134. return {}
  135. return await resp.json()
  136. except aiohttp.ClientError as exc:
  137. if is_post:
  138. self._last_post_error = str(exc)
  139. logger.error("MM API %s %s network error: %s", method, path, exc)
  140. return {}
  141. async def _api_get(self, path: str) -> dict[str, Any]:
  142. return await self._api("GET", path)
  143. async def _api_post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
  144. return await self._api("POST", path, payload)
  145. def _last_post_failure_is_broken_thread_root(self) -> bool:
  146. """Return True only for clear invalid/missing Mattermost thread roots."""
  147. body = (self._last_post_error or "").lower()
  148. if self._last_post_status not in {400, 404} or not body:
  149. return False
  150. return (any(marker in body for marker in ("root_id", "rootid", "root id", "thread", "post"))
  151. and any(marker in body for marker in ("invalid", "not found", "does not exist", "missing")))
  152. async def _post_preserving_thread(
  153. self, chat_id: str, payload: dict[str, Any], metadata: _Metadata) -> dict[str, Any]:
  154. """Post once, optionally falling back flat for final notify content."""
  155. data = await self._api_post("posts", payload)
  156. if (data or "root_id" not in payload or not (isinstance(metadata, dict) and metadata.get("notify"))
  157. or not self._last_post_failure_is_broken_thread_root()):
  158. return data
  159. flat_payload = {k: v for k, v in payload.items() if k != "root_id"}
  160. body = str(flat_payload.get("message") or "")
  161. flat_payload["message"] = self.warning_text(
  162. ("⚠️ Mattermost thread delivery failed; posting final reply in channel.\n\n" + body).strip(), body)
  163. logger.warning("Mattermost: falling back to flat channel delivery for notify-worthy post in %s", chat_id)
  164. return await self._api_post("posts", flat_payload)
  165. async def _post_message(self, chat_id: str, message: str, reply_to: Optional[str], metadata: _Metadata,
  166. file_ids: Optional[list[str]] = None) -> dict[str, Any]:
  167. """Build a mentions-disabled post payload (+ optional root_id) and post it."""
  168. base: dict[str, Any] = {"channel_id": chat_id, "message": message}
  169. if file_ids is not None:
  170. base["file_ids"] = file_ids
  171. payload = _with_mentions_disabled(base)
  172. if self._reply_mode == "thread":
  173. # root_id from reply_to, else metadata["thread_id"]/["root_id"], resolved to the true thread root.
  174. candidate = reply_to or (
  175. isinstance(metadata, dict) and (metadata.get("thread_id") or metadata.get("root_id")))
  176. if candidate:
  177. payload["root_id"] = await self._resolve_root_id(str(candidate))
  178. return await self._post_preserving_thread(chat_id, payload, metadata)
  179. async def _post_with_file(self, chat_id: str, file_id: str, caption: Optional[str], reply_to: Optional[str],
  180. metadata: _Metadata) -> SendResult:
  181. return _post_result(await self._post_message(chat_id, caption or "", reply_to, metadata, [file_id]),
  182. _POST_WITH_FILE_ERROR)
  183. async def _upload_file(self, channel_id: str, file_data: bytes, filename: str,
  184. content_type: str = "application/octet-stream") -> Optional[str]:
  185. """Upload a file and return its file ID, or None on failure."""
  186. import aiohttp
  187. form = aiohttp.FormData()
  188. form.add_field("channel_id", channel_id)
  189. form.add_field("files", file_data, filename=filename, content_type=content_type)
  190. async with self._session.post(f"{self._base_url}/api/v4/files", headers=self._auth_header(), data=form,
  191. timeout=aiohttp.ClientTimeout(total=60)) as resp:
  192. if resp.status >= 400:
  193. body = await resp.text()
  194. logger.error("MM file upload → %s: %s", resp.status, body[:200])
  195. return None
  196. infos = (await resp.json()).get("file_infos", [])
  197. return infos[0]["id"] if infos else None
  198. # --- Required overrides ---
  199. async def connect(self, *, is_reconnect: bool = False) -> bool:
  200. """Connect to Mattermost and start the WebSocket listener."""
  201. import aiohttp
  202. if not self._base_url or not self._token:
  203. logger.error("Mattermost: URL or token not configured")
  204. return False
  205. self._session = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30), trust_env=gateway_trust_env())
  206. self._closing = False
  207. me = await self._api_get("users/me")
  208. if not me or "id" not in me:
  209. logger.error("Mattermost: failed to authenticate — check MATTERMOST_TOKEN and MATTERMOST_URL")
  210. await self._session.close()
  211. return False
  212. self._bot_user_id, self._bot_username = me["id"], me.get("username", "")
  213. logger.info(
  214. "Mattermost: authenticated as @%s (%s) on %s", self._bot_username, self._bot_user_id, self._base_url)
  215. self._ws_task = asyncio.create_task(self._ws_loop())
  216. self._mark_connected()
  217. self._wire_plugin_handlers(None) # plugin-registered native handlers
  218. return True
  219. async def disconnect(self) -> None:
  220. self._closing = True
  221. await cancel_task(self._ws_task)
  222. if self._reconnect_task and not self._reconnect_task.done():
  223. self._reconnect_task.cancel()
  224. if self._ws:
  225. await self._ws.close()
  226. self._ws = None
  227. if self._session and not self._session.closed:
  228. await self._session.close()
  229. logger.info("Mattermost: disconnected")
  230. async def _resolve_root_id(self, post_id: str) -> str:
  231. """Resolve a post_id to its thread root_id (a reply's own ID causes "Invalid RootId parameter")."""
  232. if not post_id:
  233. return post_id
  234. data = await self._api_get(f"posts/{post_id}")
  235. return data["root_id"] if data and data.get("root_id") else post_id
  236. async def send(
  237. self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: _Metadata = None) -> SendResult:
  238. """Send a message (or multiple chunks) to a channel; reply_to / metadata["thread_id"] is the root post."""
  239. if not content:
  240. return SendResult(success=True)
  241. result = SendResult(success=True)
  242. for chunk in self.truncate_message(self.format_message(content), MAX_POST_LENGTH):
  243. result = _post_result(await self._post_message(chat_id, chunk, reply_to, metadata), "Failed to create post")
  244. if not result.success:
  245. break
  246. return result
  247. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  248. data = await self._api_get(f"channels/{chat_id}")
  249. if not data:
  250. return {"name": chat_id, "type": "channel"}
  251. return {"name": data.get("display_name") or data.get("name") or chat_id,
  252. "type": _CHANNEL_TYPE_MAP.get(data.get("type", "O"), "channel")}
  253. # --- Optional overrides ---
  254. async def send_typing(self, chat_id: str, metadata: _Metadata = None) -> None:
  255. await self._api_post(f"users/{self._bot_user_id}/typing", {"channel_id": chat_id})
  256. async def edit_message(self, chat_id: str, message_id: str, content: str, *, finalize: bool = False) -> SendResult:
  257. payload = _with_mentions_disabled({"message": self.format_message(content)})
  258. return _post_result(await self._api("PUT", f"posts/{message_id}/patch", payload), "Failed to edit post")
  259. async def send_image(self, chat_id: str, image_url: str, caption: Optional[str] = None,
  260. reply_to: Optional[str] = None, metadata: _Metadata = None) -> SendResult:
  261. return await self._send_url_as_file(chat_id, image_url, caption, reply_to, "image", metadata)
  262. async def send_image_file(self, chat_id: str, image_path: str, caption: Optional[str] = None,
  263. reply_to: Optional[str] = None, metadata: _Metadata = None) -> SendResult:
  264. return await self._send_local_file(chat_id, image_path, caption, reply_to, metadata=metadata)
  265. async def send_document(
  266. self, chat_id: str, file_path: str, caption: Optional[str] = None, file_name: Optional[str] = None,
  267. reply_to: Optional[str] = None, metadata: _Metadata = None) -> SendResult:
  268. return await self._send_local_file(chat_id, file_path, caption, reply_to, file_name, metadata)
  269. async def send_voice(self, chat_id: str, audio_path: str, caption: Optional[str] = None,
  270. reply_to: Optional[str] = None, metadata: _Metadata = None, **kwargs: Any) -> SendResult:
  271. return await self._send_local_file(chat_id, audio_path, caption, reply_to, metadata=metadata)
  272. async def send_video(self, chat_id: str, video_path: str, caption: Optional[str] = None,
  273. reply_to: Optional[str] = None, metadata: _Metadata = None) -> SendResult:
  274. return await self._send_local_file(chat_id, video_path, caption, reply_to, metadata=metadata)
  275. def format_message(self, content: str) -> str:
  276. """Mattermost renders standard Markdown; reduce ![alt](url) to the bare URL (inline preview)."""
  277. return re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", r"\2", content)
  278. # --- File helpers ---
  279. async def _send_url_as_file(self, chat_id: str, url: str, caption: Optional[str], reply_to: Optional[str],
  280. kind: str = "file", metadata: _Metadata = None) -> SendResult:
  281. """Download a URL and upload it as a file attachment (text fallback with the URL on failure)."""
  282. from tools.url_safety import is_safe_url
  283. async def fallback() -> SendResult:
  284. return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to, metadata=metadata)
  285. if not is_safe_url(url):
  286. logger.warning("Mattermost: blocked unsafe URL (SSRF protection)")
  287. return await fallback()
  288. import aiohttp
  289. for attempt in range(3): # retry 5xx/429 and network errors twice with linear backoff
  290. try:
  291. async with self._session.get(url, timeout=aiohttp.ClientTimeout(total=30)) as resp:
  292. if (resp.status >= 500 or resp.status == 429) and attempt < 2:
  293. logger.debug("Mattermost download retry %d/2 for %s (status %d)",
  294. attempt + 1, url[:80], resp.status)
  295. elif resp.status >= 400:
  296. return await fallback()
  297. else:
  298. file_data, ct = await resp.read(), resp.content_type or "application/octet-stream"
  299. break
  300. except (TimeoutError, aiohttp.ClientError) as exc:
  301. if attempt == 2:
  302. logger.warning("Mattermost: failed to download %s after %d attempts: %s", url, attempt + 1, exc)
  303. return await fallback()
  304. await asyncio.sleep(1.5 * (attempt + 1))
  305. file_id = await self._upload_file(chat_id, file_data, _url_filename(url, f"{kind}.png"), ct)
  306. return await self._post_with_file(chat_id, file_id, caption, reply_to, metadata) if file_id else await fallback()
  307. async def _send_local_file(
  308. self, chat_id: str, file_path: str, caption: Optional[str], reply_to: Optional[str],
  309. file_name: Optional[str] = None, metadata: _Metadata = None) -> SendResult:
  310. """Upload a local file and attach it to a post."""
  311. p = Path(file_path)
  312. if not p.exists():
  313. logger.warning("Mattermost: local file not found, skipping: %s", file_path)
  314. return SendResult(success=True, message_id=None)
  315. fname = file_name or p.name
  316. file_id = await self._upload_file(chat_id, p.read_bytes(), fname,
  317. mimetypes.guess_type(fname)[0] or "application/octet-stream")
  318. if not file_id:
  319. return SendResult(success=False, error="File upload failed")
  320. return await self._post_with_file(chat_id, file_id, caption, reply_to, metadata)
  321. async def _load_batch_image(self, image_url: str, index: int) -> Optional[tuple[bytes, str, str]]:
  322. """Read a file:// or remote image for a batch post → (data, filename, content_type), or None to skip."""
  323. import aiohttp
  324. if image_url.startswith("file://"):
  325. local_path = _unquote(image_url[7:])
  326. p = Path(local_path)
  327. if not p.exists():
  328. logger.warning("Mattermost: skipping missing image %s", local_path)
  329. return None
  330. return p.read_bytes(), p.name, mimetypes.guess_type(p.name)[0] or "image/png"
  331. from tools.url_safety import is_safe_url
  332. if not is_safe_url(image_url):
  333. logger.warning("Mattermost: blocked unsafe image URL in batch")
  334. return None
  335. try:
  336. async with self._session.get(image_url, timeout=aiohttp.ClientTimeout(total=30)) as resp:
  337. if resp.status >= 400:
  338. logger.warning("Mattermost: failed to download image (HTTP %d): %s", resp.status, image_url[:80])
  339. return None
  340. file_data, ct = await resp.read(), resp.content_type or "image/png"
  341. except Exception as dl_err:
  342. logger.warning("Mattermost: download failed for %s: %s", image_url[:80], dl_err)
  343. return None
  344. return file_data, _url_filename(image_url, f"image_{index}.png"), ct
  345. async def send_multiple_images(self, chat_id: str, images: list[tuple[str, str]],
  346. metadata: _Metadata = None, human_delay: float = 0.0) -> SendResult:
  347. """Send a batch of images as one post; chunked at Mattermost's 5-``file_ids`` cap, each chunk
  348. falling back to the base per-image loop on failure."""
  349. if not images:
  350. return SendResult(success=False, error="no images to send")
  351. chunks = [images[i:i + 5] for i in range(0, len(images), 5)] # Mattermost post file_ids cap
  352. delivered = False
  353. for chunk_idx, chunk in enumerate(chunks):
  354. if human_delay > 0 and chunk_idx > 0:
  355. await asyncio.sleep(human_delay)
  356. file_ids, caption_parts = [], []
  357. try:
  358. for image_url, alt_text in chunk:
  359. if alt_text:
  360. caption_parts.append(alt_text)
  361. loaded = await self._load_batch_image(image_url, len(file_ids))
  362. if loaded is not None and (fid := await self._upload_file(chat_id, *loaded)):
  363. file_ids.append(fid)
  364. if not file_ids:
  365. continue
  366. logger.info("Mattermost: sending %d image(s) as single post (chunk %d/%d)",
  367. len(file_ids), chunk_idx + 1, len(chunks))
  368. data = await self._post_message(chat_id, "\n".join(caption_parts), None, metadata, file_ids)
  369. if data and "id" in data:
  370. delivered = True
  371. else:
  372. logger.warning("Mattermost: multi-image post failed, falling back")
  373. fallback = await super().send_multiple_images(chat_id, chunk, metadata, human_delay=human_delay)
  374. delivered = delivered or fallback.success
  375. except Exception as e:
  376. logger.warning("Mattermost: multi-image send failed (chunk %d/%d), falling back: %s",
  377. chunk_idx + 1, len(chunks), e, exc_info=True)
  378. fallback = await super().send_multiple_images(chat_id, chunk, metadata, human_delay=human_delay)
  379. delivered = delivered or fallback.success
  380. return SendResult(success=delivered, error=None if delivered else "all images failed to send")
  381. # --- WebSocket ---
  382. async def _ws_loop(self) -> None:
  383. """Connect to the WebSocket and listen for events, reconnecting on failure."""
  384. import aiohttp
  385. import random
  386. delay = _RECONNECT_BASE_DELAY
  387. while not self._closing:
  388. try:
  389. await self._ws_connect_and_listen()
  390. delay = _RECONNECT_BASE_DELAY # clean disconnect — reset backoff
  391. except asyncio.CancelledError:
  392. return
  393. except Exception as exc:
  394. if self._closing:
  395. return
  396. # Permanent auth failure: escalate via the fatal-error hook (a bare return leaves is_connected()
  397. # healthy with a dead listener). Type-based: substring "401" matching misclassified transient errors.
  398. if isinstance(exc, aiohttp.WSServerHandshakeError) and exc.status in {401, 403}:
  399. logger.error("Mattermost WS auth failed (HTTP %d) — stopping reconnect", exc.status)
  400. # Escalate through the fatal-error hook instead of a bare return: the old silent exit
  401. # left _running True, so is_connected() kept reporting healthy while the listener was
  402. # dead and the gateway was never told (OOF-156 class). Type-based only — the substring
  403. # fallback that used to sit below this branch misclassified transient errors whose
  404. # message merely contained "401" (#80489).
  405. self._set_fatal_error(
  406. "mattermost_auth_error",
  407. f"Mattermost WebSocket authentication rejected (HTTP {exc.status}). The bot token is "
  408. "invalid, revoked, or lacks permission — check MATTERMOST_TOKEN and the bot account in "
  409. "the System Console.", retryable=False)
  410. await self._notify_fatal_error()
  411. return
  412. logger.warning("Mattermost WS error: %s — reconnecting in %.0fs", exc, delay)
  413. if self._closing:
  414. return
  415. await asyncio.sleep(delay + delay * _RECONNECT_JITTER * random.random())
  416. delay = min(delay * 2, _RECONNECT_MAX_DELAY)
  417. async def _ws_connect_and_listen(self) -> None:
  418. """Single WebSocket session: connect, authenticate, process events."""
  419. ws_url = re.sub(r"^http", "ws", self._base_url) + "/api/v4/websocket" # https→wss, http→ws
  420. logger.info("Mattermost: connecting to %s", ws_url)
  421. self._ws = await self._session.ws_connect(ws_url, heartbeat=30.0)
  422. await self._ws.send_json({"seq": 1, "action": "authentication_challenge", "data": {"token": self._token}})
  423. logger.info("Mattermost: WebSocket connected and authenticated")
  424. async for raw_msg in self._ws:
  425. if self._closing:
  426. return
  427. kind = raw_msg.type
  428. if kind in {kind.TEXT, kind.BINARY}:
  429. try:
  430. event = json.loads(raw_msg.data)
  431. except (json.JSONDecodeError, TypeError):
  432. continue
  433. await self._handle_ws_event(event)
  434. elif kind in {kind.ERROR, kind.CLOSE, kind.CLOSING, kind.CLOSED}:
  435. logger.info("Mattermost: WebSocket closed (%s)", kind)
  436. break
  437. def _apply_channel_gating(self, channel_id: str, message_text: str) -> Optional[str]:
  438. """Mention-gate a non-DM post; return the cleaned text, or None to ignore it. allowed_channels is a
  439. whitelist checked first (@mentions elsewhere are ignored); require_mention (default true) is
  440. bypassed in free_response_channels."""
  441. allowed_channels = _channel_id_set(_extra_or_secret(self.config.extra, "allowed_channels", "MATTERMOST_ALLOWED_CHANNELS", blank_is_unset=False))
  442. if allowed_channels and channel_id not in allowed_channels:
  443. logger.debug("Mattermost: ignoring message in non-allowed channel: %s", channel_id)
  444. return None
  445. require_mention = str(_extra_or_secret(self.config.extra, "require_mention", "MATTERMOST_REQUIRE_MENTION", "true", blank_is_unset=False)
  446. ).lower() not in {"false", "0", "no"}
  447. free_channels = _channel_id_set(
  448. _extra_or_secret(self.config.extra, "free_response_channels", "MATTERMOST_FREE_RESPONSE_CHANNELS", blank_is_unset=False))
  449. mention_patterns = [f"@{self._bot_username}", f"@{self._bot_user_id}"]
  450. has_mention = any(pattern.lower() in message_text.lower() for pattern in mention_patterns)
  451. if require_mention and channel_id not in free_channels and not has_mention:
  452. logger.debug("Mattermost: skipping non-DM message without @mention (channel=%s)", channel_id)
  453. return None
  454. if has_mention: # strip the @mention so the agent sees clean input
  455. for pattern in mention_patterns:
  456. message_text = re.sub(re.escape(pattern), "", message_text, flags=re.IGNORECASE).strip()
  457. return message_text
  458. async def _download_attachments(self, file_ids: list[str]) -> tuple[list[str], list[str]]:
  459. """Download attachments now (URLs need auth headers downstream tools lack) → (paths, mime types)."""
  460. import aiohttp
  461. from gateway.platforms.base import (
  462. cache_audio_from_bytes_async,
  463. cache_document_from_bytes_async,
  464. cache_image_from_bytes_async,
  465. )
  466. media_urls, media_types = [], []
  467. cache_fns = {"image/": cache_image_from_bytes_async, "audio/": cache_audio_from_bytes_async}
  468. for fid in file_ids:
  469. try:
  470. file_info = await self._api_get(f"files/{fid}/info")
  471. fname = file_info.get("name", f"file_{fid}")
  472. mime = file_info.get("mime_type", "application/octet-stream")
  473. async with self._session.get(
  474. f"{self._base_url}/api/v4/files/{fid}", headers=self._auth_header(),
  475. timeout=aiohttp.ClientTimeout(total=30)) as resp:
  476. if resp.status >= 400:
  477. logger.warning("Mattermost: failed to download file %s: HTTP %s", fid, resp.status)
  478. continue
  479. file_data = await resp.read()
  480. prefix = next((p for p in cache_fns if mime.startswith(p)), None)
  481. if prefix:
  482. media_urls.append(
  483. await cache_fns[prefix](file_data, Path(fname).suffix or _INBOUND_CACHE_EXT[prefix]))
  484. else:
  485. media_urls.append(await cache_document_from_bytes_async(file_data, fname))
  486. media_types.append(mime)
  487. except Exception as exc:
  488. logger.warning("Mattermost: error downloading file %s: %s", fid, exc)
  489. return media_urls, media_types
  490. async def _handle_ws_event(self, event: dict[str, Any]) -> None:
  491. if event.get("event") != "posted":
  492. return
  493. data = event.get("data", {})
  494. try:
  495. post = json.loads(data.get("post") or "")
  496. except (json.JSONDecodeError, TypeError):
  497. return
  498. # Ignore own messages, system posts and redeliveries.
  499. sender_id, post_id = post.get("user_id", ""), post.get("id", "")
  500. if sender_id == self._bot_user_id or post.get("type") or self._dedup.is_duplicate(post_id):
  501. return
  502. channel_id, is_dm = post.get("channel_id", ""), data.get("channel_type", "O") == "D"
  503. message_text = post.get("message", "")
  504. if not is_dm: # DMs need no gating; channels are mention-gated.
  505. message_text = self._apply_channel_gating(channel_id, message_text)
  506. if message_text is None:
  507. return
  508. # Thread support: replies use root_id; in thread mode a top-level channel post is itself a valid root.
  509. thread_id = post.get("root_id") or None
  510. if not thread_id and self._reply_mode == "thread" and not is_dm and post_id:
  511. thread_id = post_id
  512. if message_text[:1].isspace() and message_text.lstrip().startswith("/"):
  513. message_text = message_text.lstrip()
  514. media_urls, media_types = await self._download_attachments(post.get("file_ids") or [])
  515. if message_text.startswith("/"):
  516. msg_type = MessageType.COMMAND
  517. elif media_types:
  518. msg_type = next((mt for prefix, mt in _MEDIA_MSG_TYPES if any(m.startswith(prefix) for m in media_types)),
  519. MessageType.DOCUMENT)
  520. else:
  521. msg_type = MessageType.TEXT
  522. source = self.build_source(
  523. chat_id=channel_id, chat_type=_CHANNEL_TYPE_MAP.get(data.get("channel_type", "O"), "channel"),
  524. user_id=sender_id, user_name=data.get("sender_name", "").lstrip("@") or sender_id,
  525. thread_id=thread_id, message_id=post_id,
  526. # A bot account's post carries props.from_bot (a string "true" on the wire).
  527. is_bot=str((post.get("props") or {}).get("from_bot", "")).lower() == "true"
  528. or self._is_configured_bot_user(sender_id))
  529. from gateway.platforms.base import resolve_channel_prompt
  530. await self.handle_message(MessageEvent(
  531. text=message_text, message_type=msg_type, source=source, raw_message=post, message_id=post_id,
  532. media_urls=media_urls, media_types=media_types,
  533. channel_prompt=resolve_channel_prompt(self.config.extra, channel_id, None)))
  534. # --- Plugin standalone-send (out-of-process cron delivery via Mattermost REST) ---
  535. async def _standalone_send(pconfig, chat_id: str, message: str, *, thread_id: Optional[str] = None,
  536. media_files: Optional[list] = None, force_document: bool = False) -> dict[str, Any]:
  537. """Send via the Mattermost v4 REST API without a live gateway adapter (out-of-process cron).
  538. Token/URL: ``pconfig`` with env fallback. ``media_files`` upload via ``POST /files`` and attach by
  539. file_id; ``thread_id`` becomes ``root_id``. ``force_document`` is signature parity only (unused).
  540. """
  541. try:
  542. import aiohttp
  543. except ImportError:
  544. return send_error("aiohttp not installed. Run: pip install aiohttp")
  545. base_url, token = _url_and_token(pconfig)
  546. base_url, token = base_url.rstrip("/"), token.strip()
  547. if not base_url or not token:
  548. return send_error("Mattermost standalone send: MATTERMOST_URL and MATTERMOST_TOKEN must both be set")
  549. upload_headers = {"Authorization": f"Bearer {token}"}
  550. headers = {**upload_headers, "Content-Type": "application/json"}
  551. try:
  552. # One ClientSession (with proxy) covers the optional uploads + final post.
  553. from gateway.platforms.base import resolve_proxy_url, proxy_kwargs_for_aiohttp
  554. _sess_kw, _req_kw = proxy_kwargs_for_aiohttp(resolve_proxy_url(platform_env_var="MATTERMOST_PROXY"))
  555. async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=60), **_sess_kw) as session:
  556. file_ids: list[str] = []
  557. for media in media_files or []:
  558. file_path = media.get("path") if isinstance(media, dict) else media
  559. if not file_path or not os.path.exists(file_path):
  560. continue
  561. form = aiohttp.FormData()
  562. form.add_field("channel_id", chat_id) # required so the server can attribute the upload
  563. form.add_field("files", await asyncio.to_thread(Path(file_path).read_bytes),
  564. filename=os.path.basename(file_path))
  565. async with session.post(f"{base_url}/api/v4/files", data=form, headers=upload_headers,
  566. **_req_kw) as upload_resp:
  567. if upload_resp.status not in {200, 201}:
  568. body = await upload_resp.text()
  569. return send_error(f"Mattermost file upload failed ({upload_resp.status}): {body[:400]}")
  570. upload_data = await upload_resp.json()
  571. file_ids.extend(info["id"] for info in upload_data.get("file_infos", []) if info.get("id"))
  572. payload: dict[str, Any] = {"channel_id": chat_id, "message": message}
  573. if thread_id:
  574. payload["root_id"] = thread_id
  575. if file_ids:
  576. payload["file_ids"] = file_ids
  577. async with session.post(f"{base_url}/api/v4/posts", headers=headers, json=payload, **_req_kw) as resp:
  578. if resp.status not in {200, 201}:
  579. body = await resp.text()
  580. return send_error(f"Mattermost API error ({resp.status}): {body[:400]}")
  581. data = await resp.json()
  582. return {"success": True, "platform": "mattermost", "chat_id": chat_id, "message_id": data.get("id")}
  583. except aiohttp.ClientError as exc:
  584. return send_error(f"Mattermost send failed (network): {exc}")
  585. except Exception as exc:
  586. return send_error(f"Mattermost send failed: {exc}")
  587. # --- Interactive setup wizard ---
  588. def interactive_setup() -> None:
  589. """Guide the user through Mattermost bot setup (URL + token, allowlist, home channel)."""
  590. from hermes_cli.config import remove_env_value, save_env_value
  591. from hermes_cli.cli_output import prompt, print_header, print_info, print_success
  592. from hermes_cli.setup_platforms import declines_reconfigure
  593. def info(*lines: str) -> None:
  594. for line in lines:
  595. print_info(line)
  596. print_header("Mattermost")
  597. if declines_reconfigure("Mattermost", "Reconfigure Mattermost?", "MATTERMOST_TOKEN"):
  598. return
  599. info("Works with any self-hosted Mattermost instance.",
  600. " 1. In Mattermost: Integrations → Bot Accounts → Add Bot Account", " 2. Copy the bot token")
  601. print()
  602. mm_url = prompt("Mattermost server URL (e.g. https://mm.example.com)")
  603. if mm_url:
  604. save_env_value("MATTERMOST_URL", mm_url.rstrip("/"))
  605. token = prompt("Bot token", password=True)
  606. if not token:
  607. return
  608. save_env_value("MATTERMOST_TOKEN", token)
  609. print_success("Mattermost token saved")
  610. print()
  611. info("🔒 Security: Restrict who can use your bot",
  612. " Find your user ID (the profile dialog does not show it):",
  613. " Admins: System Console → User Management → Users → open your user.",
  614. " Anyone: while logged in, open <server>/api/v4/users/me in a browser tab.",
  615. " With the bot token: GET <server>/api/v4/users/username/<your-username>.",
  616. " Copy the \"id\" field. /users/me with the bot token returns the bot's ID.")
  617. print()
  618. allowed_users = prompt("Allowed user IDs (comma-separated, leave empty for open access)")
  619. if allowed_users:
  620. save_env_value("MATTERMOST_ALLOWED_USERS", allowed_users.replace(" ", ""))
  621. print_success("Mattermost allowlist configured")
  622. else:
  623. print_info("⚠️ No allowlist set - anyone who can message the bot can use it!")
  624. print()
  625. info("📬 Home Channel: where Hermes delivers cron job results and notifications.",
  626. " To get a channel ID: click channel name → View Info → copy the ID",
  627. " You can also set this later by typing /set-home in a Mattermost channel.")
  628. home_channel = prompt("Home channel ID (leave empty to set later with /set-home)").strip()
  629. if home_channel:
  630. save_env_value("MATTERMOST_HOME_CHANNEL", home_channel)
  631. elif remove_env_value("MATTERMOST_HOME_CHANNEL"):
  632. print_info("Home channel cleared.")
  633. print_info(" Open config in your editor: hermes config edit")
  634. # --- YAML → env config bridge (apply_yaml_config_fn) ---
  635. _YAML_BRIDGE = ( # (yaml key, env var, kind) for apply_yaml_bridge; allowed_channels is a whitelist
  636. ("require_mention", "MATTERMOST_REQUIRE_MENTION", "lower"),
  637. ("free_response_channels", "MATTERMOST_FREE_RESPONSE_CHANNELS", "csv"),
  638. ("allowed_channels", "MATTERMOST_ALLOWED_CHANNELS", "csv"))
  639. def _apply_yaml_config(yaml_cfg: dict, mattermost_cfg: dict) -> dict | None:
  640. """``apply_yaml_config_fn`` (#24836 / #25443): ``config.yaml`` ``mattermost:`` keys → env vars (env wins;
  641. skipped under a multiplexed secondary profile) + ``PlatformConfig.extra`` (extra-first readers)."""
  642. return _apply_yaml_bridge(mattermost_cfg, _YAML_BRIDGE)
  643. _is_connected = _env_is_connected("MATTERMOST_TOKEN", "MATTERMOST_URL")
  644. # System-prompt platform hint (PlatformEntry.platform_hint); cached-prompt bytes, keep stable.
  645. _PLATFORM_HINT = (
  646. "You are in a Mattermost workspace communicating with your user. Mattermost renders standard "
  647. "Markdown — headings, bold, italic, code blocks, and tables all work. You can send media files "
  648. "natively: include MEDIA:/absolute/path/to/file in your response. Images (.jpg, .png, .webp) are "
  649. "uploaded as photo attachments, audio and video as file attachments. Image URLs in markdown format "
  650. "![alt](url) are rendered as inline previews automatically."
  651. )
  652. def register(ctx) -> None:
  653. """Plugin entry point — called by the Hermes plugin system."""
  654. from . import gateway_env # env -> GatewayConfig bridge (gateway.config_env)
  655. ctx.register_platform(
  656. name="mattermost", label="Mattermost", adapter_factory=MattermostAdapter,
  657. dashboard_description="Connect Hermes to Mattermost channels and direct messages.",
  658. docs_url="https://mattermost.com/deploy/",
  659. dashboard_env_vars=("MATTERMOST_URL", "MATTERMOST_TOKEN", "MATTERMOST_ALLOWED_USERS"),
  660. check_fn=check_mattermost_requirements, validate_config=validate_mattermost_config,
  661. is_connected=_is_connected, required_env=["MATTERMOST_URL", "MATTERMOST_TOKEN"],
  662. install_hint="pip install aiohttp", setup_fn=interactive_setup,
  663. apply_yaml_config_fn=_apply_yaml_config, # YAML→env bridge (see _YAML_BRIDGE)
  664. cron_deliver_env_var="MATTERMOST_HOME_CHANNEL",
  665. standalone_sender_fn=_standalone_send, # out-of-process cron; without it `deliver=mattermost` fails
  666. max_message_length=MAX_POST_LENGTH, emoji="💬", allow_update_command=True,
  667. platform_hint=_PLATFORM_HINT,
  668. display_tier="medium",
  669. env_overrides=gateway_env.ENV_OVERRIDES,
  670. env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS, **gateway_env.AUTHZ,
  671. )