buzz_cursors.py 4.0 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788
  1. """Durable per-channel receive cursors for the Buzz adapter (#90464): a restart resumes from the saved
  2. cursor instead of reseeding from history and marking downtime arrivals as seen."""
  3. import asyncio
  4. import json
  5. import logging
  6. from pathlib import Path
  7. logger = logging.getLogger(__name__)
  8. _SEEN_CAP = 500 # per-channel de-dupe set bound (events)
  9. _CURSOR_STATE_SUBDIR = "buzz" # per-channel cursors survive a restart under HERMES_HOME
  10. _CURSOR_STATE_FILENAME = "channel-cursors.json"
  11. class BuzzCursorMixin:
  12. @staticmethod
  13. def _cursor_path() -> Path:
  14. from hermes_constants import get_hermes_home
  15. return get_hermes_home() / _CURSOR_STATE_SUBDIR / _CURSOR_STATE_FILENAME
  16. def _load_cursors(self) -> None:
  17. """Read persisted cursors; another identity/relay's file is ignored (ids collide), failures seed from history."""
  18. self._restored_cursors = {}
  19. try:
  20. if not (path := self._cursor_path()).exists():
  21. return
  22. data = json.loads(path.read_text(encoding="utf-8-sig"))
  23. except Exception:
  24. logger.debug("Buzz: could not read channel cursors", exc_info=True)
  25. return
  26. if not isinstance(data, dict) or data.get("identity") != self._self_pubkey or data.get("relay") != self.relay_url:
  27. return
  28. if not isinstance(channels := data.get("channels"), dict):
  29. return
  30. for channel_id, entry in channels.items():
  31. if not isinstance(entry, dict):
  32. continue
  33. try:
  34. last_ts = int(entry.get("last_ts") or 0)
  35. except (TypeError, ValueError):
  36. continue
  37. raw_seen = entry.get("seen")
  38. seen = [str(event_id) for event_id in raw_seen][-_SEEN_CAP:] if isinstance(raw_seen, list) else []
  39. self._restored_cursors[str(channel_id)] = {"chat_type": str(entry.get("chat_type") or ""), "last_ts": last_ts, "seen": seen}
  40. def _cursor_payload(self) -> dict:
  41. """Snapshot of every watched channel's cursor (taken on the loop: ``_channel_state`` is loop-owned)."""
  42. channels = {
  43. channel_id: {
  44. "chat_type": state.get("chat_type") or "group", "last_ts": int(state.get("last_ts") or 0),
  45. "seen": list(state.get("seen") or ()),
  46. }
  47. for channel_id, state in self._channel_state.items()
  48. }
  49. return {"identity": self._self_pubkey, "relay": self.relay_url, "channels": channels}
  50. def _save_cursors(self) -> None:
  51. """Persist every watched channel's cursor. Never raises."""
  52. self._write_cursors(self._cursor_path(), self._cursor_payload())
  53. @staticmethod
  54. def _write_cursors(path: Path, payload: dict) -> None:
  55. try:
  56. from utils import atomic_json_write
  57. atomic_json_write(path, payload, indent=None)
  58. except Exception:
  59. logger.debug("Buzz: could not persist channel cursors", exc_info=True)
  60. @staticmethod
  61. def _cursor_mark(state: dict) -> tuple:
  62. """Cheap change detector for one channel's cursor."""
  63. seen = state.get("seen") or ()
  64. return int(state.get("last_ts") or 0), len(seen), (next(reversed(seen), None) if seen else None)
  65. def _cursor_writer(self):
  66. """A write of the cursor as it stands now. A deferred write runs after the reader marked later
  67. events seen before their dispatch committed, so it must never re-read the live state; and a
  68. write older than one already landed is skipped, so the file never moves back."""
  69. payload = self._cursor_payload()
  70. self._cursor_snapshots = generation = self._cursor_snapshots + 1
  71. async def persist() -> None:
  72. # The write fsyncs + renames, and on the WebSocket transport this runs once per inbound event.
  73. async with self._cursor_write_lock:
  74. if generation > self._cursor_written:
  75. self._cursor_written = generation
  76. await asyncio.to_thread(self._write_cursors, self._cursor_path(), payload)
  77. return persist