webhook_coalesce.py 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153
  1. """Per-route event coalescing for the webhook adapter (opt-in ``coalesce`` route block).
  2. Rapid distinct events on one logical entity (five pushes to a PR, a burst of ticket edits) each
  3. carry a fresh delivery ID, so idempotency cannot suppress them and every event wakes an agent
  4. run. Coalescing groups events by a payload-derived key and debounces them: only the LATEST event
  5. of a group is dispatched once the quiet window passes, bounded by ``max_wait_seconds`` past the
  6. group's first event so a steady stream cannot starve dispatch (one durable run per entity, stale
  7. heads superseded). #92066
  8. """
  9. from __future__ import annotations
  10. import asyncio
  11. import logging
  12. import re
  13. import time
  14. from dataclasses import dataclass
  15. from typing import Any, Callable, Dict, Optional
  16. logger = logging.getLogger(__name__)
  17. DEFAULT_WINDOW_SECONDS = 30.0
  18. DEFAULT_MAX_WAIT_SECONDS = 300.0
  19. _PLACEHOLDER_RE = re.compile(r"\{[a-zA-Z0-9_.]+\}")
  20. def validate_coalesce_config(route_name: str, route: dict) -> None:
  21. """Startup validation of a route's ``coalesce`` block; raises ValueError so a typo'd route fails
  22. fast instead of silently dispatching every event. Agent-mode routes only."""
  23. coalesce = route.get("coalesce")
  24. if coalesce is None:
  25. return
  26. for exclusive in ("deliver_only", "cron_job"):
  27. if route.get(exclusive):
  28. raise ValueError(f"[webhook] Route '{route_name}' combines {exclusive} with coalesce. Coalescing only "
  29. f"applies to agent-mode routes.")
  30. key = coalesce.get("key") if isinstance(coalesce, dict) else None
  31. if not isinstance(key, str) or not key.strip():
  32. raise ValueError(f"[webhook] Route '{route_name}' has a coalesce block without a non-empty string 'key'. "
  33. f"Set coalesce.key to a payload field (e.g. 'pull_request.number') or a template "
  34. f"(e.g. '{{repository.full_name}}#{{number}}').")
  35. for field in ("window_seconds", "max_wait_seconds"):
  36. value = coalesce.get(field)
  37. if value is not None and (isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0):
  38. raise ValueError(f"[webhook] Route '{route_name}' coalesce.{field} must be a positive number, got {value!r}.")
  39. @dataclass
  40. class PendingEvent:
  41. """Newest event of a coalesce group plus the group's bookkeeping."""
  42. payload: Any
  43. prompt: str
  44. delivery_id: str
  45. first_at: float
  46. count: int
  47. dispatch_kwargs: dict[str, Any]
  48. superseded: tuple[str, ...] = () # delivery ids of the earlier events this one replaced
  49. def prompt_with_note(self) -> str:
  50. if self.count <= 1:
  51. return self.prompt
  52. return (f"{self.prompt}\n\n(Note: {self.count} webhook events for this item arrived in quick succession "
  53. f"and were coalesced — this is the most recent one; earlier events are superseded.)")
  54. class WebhookCoalescer:
  55. """Debounce-and-supersede buffer. ``dispatch(payload, prompt, delivery_id, **kwargs)`` is the adapter's
  56. agent-run spawner. Only ever driven from the aiohttp event loop → no locking."""
  57. def __init__(self, dispatch: Callable[..., Any], render: Callable[[str, dict, str, str], str]):
  58. self._dispatch = dispatch
  59. self._render = render
  60. self._pending: dict[str, PendingEvent] = {}
  61. self._timers: dict[str, asyncio.Task] = {}
  62. @property
  63. def pending(self) -> dict[str, PendingEvent]:
  64. return self._pending
  65. def group_key(self, route_name: str, key_template: str, payload: dict, event_type: str) -> Optional[str]:
  66. """``"{route}|{rendered key}"`` for a bare dotted field or a brace template; ``None`` when a field did
  67. not resolve — unrelated entities must not collapse into one shared group (review finding on #92066)."""
  68. template = key_template.strip()
  69. if "{" not in template:
  70. template = "{" + template + "}"
  71. rendered = self._render(template, payload, event_type, route_name)
  72. if _PLACEHOLDER_RE.search(rendered):
  73. return None
  74. return f"{route_name}|{rendered}"
  75. def enqueue(self, *, route_name: str, coalesce: dict, payload: dict, event_type: str, prompt: str,
  76. delivery_id: str, now: float, **dispatch_kwargs) -> bool:
  77. """Buffer one event; False when the key did not resolve and the caller must dispatch immediately."""
  78. group_key = self.group_key(route_name, coalesce["key"], payload, event_type)
  79. if group_key is None:
  80. logger.info("[webhook] coalesce key %r unresolved for delivery %s on route %s — dispatching immediately",
  81. coalesce["key"], delivery_id, route_name)
  82. return False
  83. window = float(coalesce.get("window_seconds", DEFAULT_WINDOW_SECONDS))
  84. max_wait = float(coalesce.get("max_wait_seconds", DEFAULT_MAX_WAIT_SECONDS))
  85. existing = self._pending.get(group_key)
  86. first_at = existing.first_at if existing else now
  87. count = existing.count + 1 if existing else 1
  88. dispatch_kwargs = {**dispatch_kwargs, "route_name": route_name, "event_type": event_type}
  89. superseded = (*existing.superseded, existing.delivery_id) if existing else ()
  90. self._pending[group_key] = PendingEvent(payload=payload, prompt=prompt, delivery_id=delivery_id,
  91. first_at=first_at, count=count, dispatch_kwargs=dispatch_kwargs,
  92. superseded=superseded)
  93. if existing is not None:
  94. logger.info("[webhook] coalesced delivery %s superseded by %s (group=%s, %d events)",
  95. existing.delivery_id, delivery_id, group_key, count)
  96. old = self._timers.pop(group_key, None)
  97. if old is not None and not old.done():
  98. old.cancel()
  99. # Quiet window from now, capped at max_wait past the group's FIRST event.
  100. delay = min(window, max(0.0, first_at + max_wait - now))
  101. self._timers[group_key] = asyncio.create_task(self._timer(group_key, delay))
  102. return True
  103. async def _timer(self, group_key: str, delay: float) -> None:
  104. try:
  105. if delay > 0:
  106. await asyncio.sleep(delay)
  107. except asyncio.CancelledError:
  108. return # superseded by a newer event's timer — the pending entry stays
  109. self._timers.pop(group_key, None)
  110. entry = self._pending.pop(group_key, None)
  111. if entry is not None:
  112. self._settle(group_key, entry)
  113. def _settle(self, group_key: str, entry: PendingEvent) -> Any:
  114. logger.info("[webhook] coalesce settled group=%s events=%d delivery=%s", group_key, entry.count,
  115. entry.delivery_id)
  116. return self._dispatch(entry.payload, entry.prompt_with_note(), entry.delivery_id, time.time(),
  117. **entry.dispatch_kwargs, superseded=entry.superseded)
  118. async def flush(self) -> None:
  119. """Dispatch every pending group now and wait until each run is handed to the runner, so an adapter
  120. disconnect/reconnect drops nothing. A hard process kill still loses the current window's buffer."""
  121. for task in self._timers.values():
  122. if not task.done():
  123. task.cancel()
  124. self._timers.clear()
  125. pending, self._pending = self._pending, {}
  126. handed_off = []
  127. for group_key, entry in pending.items():
  128. try:
  129. handed_off.append(self._settle(group_key, entry))
  130. except Exception:
  131. logger.exception("[webhook] failed to flush coalesced group %s", group_key)
  132. awaitables = [t for t in handed_off if isinstance(t, asyncio.Future)]
  133. if awaitables:
  134. await asyncio.gather(*awaitables, return_exceptions=True)