Skip to content

Self-improving AI Employees for everyone

feat(events): Wave 12 generalized event framework

trohitgc457303e43d8
diff --git a/server/routers/webhook.py b/server/routers/webhook.py
index 2c0db035..187341d5 100644
--- a/server/routers/webhook.py
+++ b/server/routers/webhook.py
@@ -1,14 +1,23 @@
"""Dynamic webhook endpoint router for incoming HTTP requests.
-Works like WhatsApp trigger - uses broadcaster.send_custom_event() to dispatch
-to event_waiter which resolves waiting trigger nodes.
+Two dispatch paths:
+
+1. **Plugin-owned WebhookSource** (Wave 12 framework). Plugins register
+ a :class:`services.events.WebhookSource` for their path; the router
+ verifies the signature, shapes a :class:`WorkflowEvent`, and queues
+ it onto the source. The source's owning plugin pulls events via
+ ``source.emit()`` and dispatches into ``event_waiter``.
+2. **Legacy generic webhook** (pre-framework). Falls through to
+ ``broadcaster.send_custom_event("webhook_received", …)`` so existing
+ ``webhookTrigger`` nodes keep working untouched.
"""
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, HTTPException, Request
from fastapi.responses import JSONResponse
from typing import Dict
import asyncio
import logging
+from services.events import WEBHOOK_SOURCES
from services.status_broadcaster import get_status_broadcaster
logger = logging.getLogger(__name__)
@@ -38,10 +47,21 @@ def resolve_webhook_response(node_id: str, response_data: dict):
async def handle_webhook(path: str, request: Request):
"""Handle incoming webhook requests.
- Dispatches webhook_received event to trigger waiting webhookTrigger nodes.
- Similar to how WhatsApp events dispatch to whatsappReceive nodes.
+ Path-handler dispatch (Wave 12) runs first; legacy generic
+ dispatch is the fallback for paths nobody has claimed.
"""
- # Build webhook request data
+ source = WEBHOOK_SOURCES.get(path)
+ if source is not None:
+ try:
+ await source.handle(request)
+ except HTTPException:
+ raise
+ except Exception as e:
+ logger.exception("[Webhook] %s handler crashed: %s", path, e)
+ raise HTTPException(status_code=500, detail=str(e))
+ logger.info("[Webhook] %s %s -> %s", request.method, path, type(source).__name__)
+ return JSONResponse({"status": "received", "path": path}, status_code=200)
+
body = await request.body()
json_body = None
content_type = request.headers.get("content-type", "")
@@ -63,12 +83,9 @@ async def handle_webhook(path: str, request: Request):
logger.info(f"[Webhook] Received: {request.method} /webhook/{path}")
- # Dispatch event using broadcaster (same pattern as WhatsApp)
broadcaster = get_status_broadcaster()
await broadcaster.send_custom_event("webhook_received", webhook_data)
- # For now, always return immediate response
- # TODO: Support responseNode mode by storing Future and waiting
return JSONResponse(
content={
"status": "received",
diff --git a/server/services/events/__init__.py b/server/services/events/__init__.py
new file mode 100644
index 00000000..d9b2f0d5
--- /dev/null
+++ b/server/services/events/__init__.py
@@ -0,0 +1,54 @@
+"""Generalized event-source framework (Wave 12).
+
+Three concrete EventSource subclasses cover all current MachinaOs
+trigger integrations: ``PushEventSource`` (HTTP/RPC pushes),
+``PollingEventSource`` (interval-based pull), ``DaemonEventSource``
+(long-lived subprocess driver). Webhook flow is a thin specialisation
+of PushEventSource via :class:`WebhookSource` + the path registry in
+``server/routers/webhook.py``.
+
+The unified payload type :class:`WorkflowEvent` mirrors CloudEvents
+v1.0 verbatim — see ``envelope.py``. A back-compat shim in
+``services.event_waiter`` auto-wraps legacy ``Dict`` dispatches so
+existing plugins keep working untouched until they migrate.
+"""
+
+from __future__ import annotations
+
+from .cli import run_cli_command
+from .envelope import WorkflowEvent
+from .lifecycle import make_lifecycle_handlers, make_status_refresh
+from .source import EventSource
+from .push import PushEventSource
+from .polling import PollingEventSource
+from .daemon import DaemonEventSource
+from .triggers import BaseTriggerParams, WebhookTriggerNode
+from .webhook import WebhookSource, WEBHOOK_SOURCES, register_webhook_source
+from .verifiers import (
+ WebhookVerifier,
+ HmacVerifier,
+ StripeVerifier,
+ StandardWebhooksVerifier,
+ GitHubVerifier,
+)
+
+__all__ = [
+ "BaseTriggerParams",
+ "DaemonEventSource",
+ "EventSource",
+ "GitHubVerifier",
+ "HmacVerifier",
+ "PollingEventSource",
+ "PushEventSource",
+ "StandardWebhooksVerifier",
+ "StripeVerifier",
+ "WEBHOOK_SOURCES",
+ "WebhookSource",
+ "WebhookTriggerNode",
+ "WebhookVerifier",
+ "WorkflowEvent",
+ "make_lifecycle_handlers",
+ "make_status_refresh",
+ "register_webhook_source",
+ "run_cli_command",
+]
diff --git a/server/services/events/cli.py b/server/services/events/cli.py
new file mode 100644
index 00000000..b3c2c101
--- /dev/null
+++ b/server/services/events/cli.py
@@ -0,0 +1,73 @@
+"""Generic CLI invocation helper.
+
+``run_cli_command`` resolves the binary on PATH, injects the
+plugin's API key via the convention flag (``--api-key`` by default),
+runs the subprocess with a timeout, captures stdout/stderr, and parses
+stdout as JSON when possible. Used by any plugin that wraps a CLI
+tool (Stripe, future GitHub-CLI / Cloudflare-Wrangler / etc.).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+from typing import Any, Dict, List, Optional, Type
+
+
+async def run_cli_command(
+ *,
+ binary: str,
+ argv: List[str],
+ credential: Optional[Type] = None,
+ api_key_arg: str = "--api-key",
+ timeout: float = 30.0,
+) -> Dict[str, Any]:
+ """Run ``<binary> <argv> [api_key_arg <key>]`` once, return parsed JSON.
+
+ Returns a uniform envelope:
+ {"success": bool, "result": parsed-JSON-or-None,
+ "stdout": str, "stderr": str, "error": str or None}
+ """
+ api_key: Optional[str] = None
+ if credential is not None:
+ try:
+ secrets = await credential.resolve()
+ except PermissionError:
+ return {"success": False, "error": f"{binary}: credential required"}
+ api_key = secrets.get("api_key")
+ if not api_key:
+ return {"success": False, "error": f"{binary}: credential required"}
+
+ resolved = shutil.which(binary)
+ if resolved is None:
+ return {"success": False, "error": f"{binary!r} not on PATH"}
+
+ full_argv = [resolved, *argv]
+ if api_key:
+ full_argv.extend([api_key_arg, api_key])
+
+ try:
+ proc = await asyncio.create_subprocess_exec(
+ *full_argv,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ )
+ stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+ except asyncio.TimeoutError:
+ return {"success": False, "error": f"{binary} timed out ({timeout}s)"}
+
+ out = stdout.decode(errors="replace").strip()
+ err = stderr.decode(errors="replace").strip()
+ if proc.returncode != 0:
+ return {
+ "success": False,
+ "stdout": out,
+ "stderr": err,
+ "error": err or f"exit {proc.returncode}",
+ }
+ try:
+ parsed = json.loads(out) if out else None
+ except json.JSONDecodeError:
+ parsed = None
+ return {"success": True, "result": parsed, "stdout": out, "stderr": err, "error": None}
diff --git a/server/services/events/daemon.py b/server/services/events/daemon.py
new file mode 100644
index 00000000..6c0c6df1
--- /dev/null
+++ b/server/services/events/daemon.py
@@ -0,0 +1,178 @@
+"""DaemonEventSource — long-lived subprocess (or SDK loop) that emits
+events into the framework.
+
+Used by stripe-listen, future telegram/whatsapp daemon migrations, and
+any plugin that wraps a CLI tool. The class delegates lifecycle to
+:class:`services.process_service.ProcessService` (already battle-tested:
+PATHEXT-aware, ``kill_tree`` cleanup, log capture) and adds:
+
+- typed event emission via :meth:`parse_line` (one event per stdout line,
+ optionally per stderr line)
+- declarative ``build_command(secrets) -> str`` so credential resolution
+ is uniform across daemons
+- pre-flight ``shutil.which`` check with a clear error if the binary
+ isn't on PATH
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+from pathlib import Path
+from typing import Any, AsyncIterator, ClassVar, Dict, Optional
+
+from core.logging import get_logger
+from services.process_service import get_process_service
+
+from .envelope import WorkflowEvent
+from .source import EventSource
+
+logger = get_logger(__name__)
+
+
+class DaemonEventSource(EventSource):
+ """Long-lived subprocess driver. Subclasses provide:
+
+ * :attr:`process_name` — unique name for ProcessService key
+ * :attr:`binary_name` — the executable to look up via PATH
+ * :meth:`build_command(secrets)` — full command string
+ * :meth:`parse_line(stream, line)` — turn output lines into events
+ (return ``None`` to suppress; e.g. log-only lines)
+ * :meth:`install_hint` (optional) — install URL surfaced in the
+ "binary not on PATH" error
+ """
+
+ process_name: ClassVar[str] = ""
+ binary_name: ClassVar[str] = ""
+ workflow_namespace: ClassVar[str] = "_daemon"
+ install_hint: ClassVar[str] = ""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self._pid: Optional[int] = None
+ self._lock = asyncio.Lock()
+ self._tail_task: Optional[asyncio.Task] = None
+ self._queue: asyncio.Queue[WorkflowEvent] = asyncio.Queue()
+
+ @property
+ def pid(self) -> Optional[int]:
+ return self._pid
+
+ def build_command(self, secrets: Dict) -> str:
+ raise NotImplementedError
+
+ def parse_line(self, stream: str, line: str) -> Optional[WorkflowEvent]:
+ """Override to emit events from output lines. ``stream`` is
+ ``"stdout"`` or ``"stderr"``. Returning ``None`` swallows the line."""
+ return None
+
+ def workdir(self) -> Path:
+ from core.config import Settings
+ cwd = Path(Settings().workspace_base_resolved).resolve() / self.workflow_namespace
+ cwd.mkdir(parents=True, exist_ok=True)
+ return cwd
+
+ async def _resolve_secrets(self) -> Dict[str, Any]:
+ if self.credential is None:
+ return {}
+ try:
+ return await self.credential.resolve()
+ except PermissionError:
+ return {}
+
+ async def has_credential(self) -> bool:
+ secrets = await self._resolve_secrets()
+ return bool(secrets.get("api_key"))
+
+ async def status(self) -> Dict[str, Any]:
+ return {
+ "type": self.type,
+ "running": self._started,
+ "pid": self._pid,
+ }
+
+ async def start(self) -> Dict[str, Any]:
+ async with self._lock:
+ if self._started:
+ return {"success": True, "message": "already running", "status": await self.status()}
+
+ secrets = await self._resolve_secrets()
+ if self.credential is not None and not secrets.get("api_key"):
+ return {"success": False, "error": f"{self.type}: credential required"}
+
+ if self.binary_name and shutil.which(self.binary_name) is None:
+ hint = f" Install: {self.install_hint}" if self.install_hint else ""
+ return {"success": False, "error": f"{self.binary_name!r} not on PATH.{hint}"}
+
+ cmd = self.build_command(secrets)
+ cwd = self.workdir()
+ result = await get_process_service().start(
+ name=self.process_name,
+ command=cmd,
+ workflow_id=self.workflow_namespace,
+ working_directory=str(cwd),
+ )
+ if not result.get("success"):
+ return result
+
+ self._pid = (result.get("result") or {}).get("pid")
+ self._started = True
+ self._stopped = False
+ self._tail_task = asyncio.create_task(self._tail_logs(cwd))
+ logger.info("[%s] daemon started pid=%s", self.type, self._pid)
+ return {"success": True, "message": f"started (pid {self._pid})", "status": await self.status()}
+
+ async def stop(self) -> Dict[str, Any]:
+ async with self._lock:
+ self._stopped = True
+ if self._tail_task and not self._tail_task.done():
+ self._tail_task.cancel()
+ try:
+ await self._tail_task
+ except asyncio.CancelledError:
+ pass
+ self._tail_task = None
+ await get_process_service().stop(
+ name=self.process_name, workflow_id=self.workflow_namespace,
+ )
+ self._started = False
+ self._pid = None
+ return {"success": True, "message": "disconnected"}
+
+ async def restart(self) -> Dict[str, Any]:
+ await self.stop()
+ return await self.start()
+
+ async def _tail_logs(self, cwd: Path) -> None:
+ """Tail both stdout.log and stderr.log; feed each new line to
+ :meth:`parse_line` and queue any returned events."""
+ await asyncio.gather(
+ self._tail_one(cwd / ".processes" / self.process_name / "stdout.log", "stdout"),
+ self._tail_one(cwd / ".processes" / self.process_name / "stderr.log", "stderr"),
+ )
+
+ async def _tail_one(self, path: Path, stream: str) -> None:
+ offset = 0
+ try:
+ while not self._stopped:
+ if path.exists():
+ size = path.stat().st_size
+ if size > offset:
+ with path.open("r", encoding="utf-8", errors="replace") as f:
+ f.seek(offset)
+ for raw in f:
+ if not raw.endswith("\n"):
+ break
+ line = raw.rstrip("\n")
+ offset = f.tell()
+ event = self.parse_line(stream, line)
+ if event is not None:
+ await self._queue.put(event)
+ await asyncio.sleep(0.5)
+ except asyncio.CancelledError:
+ raise
+
+ async def emit(self) -> AsyncIterator[WorkflowEvent]:
+ while not self._stopped:
+ event = await self._queue.get()
+ yield event
diff --git a/server/services/events/envelope.py b/server/services/events/envelope.py
new file mode 100644
index 00000000..e4a42b56
--- /dev/null
+++ b/server/services/events/envelope.py
@@ -0,0 +1,65 @@
+"""WorkflowEvent — CloudEvents v1.0 envelope (in-house, no external dep).
+
+Field set mirrors https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md
+verbatim so future interop with EventBridge / Knative is a JSON-schema swap.
+The MachinaOs extensions (workflow_id, trigger_node_id, correlation_id)
+ride as CloudEvents extension attributes — fully compliant with the spec.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class WorkflowEvent(BaseModel):
+ """Unified event envelope used by every EventSource."""
+
+ specversion: str = "1.0"
+ id: str = Field(default_factory=lambda: uuid4().hex)
+ source: str
+ type: str
+ time: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+ subject: Optional[str] = None
+ datacontenttype: str = "application/json"
+ dataschema: Optional[str] = None
+ data: Any = None
+
+ workflow_id: Optional[str] = None
+ trigger_node_id: Optional[str] = None
+ correlation_id: Optional[str] = None
+
+ model_config = ConfigDict(extra="allow")
+
+ @classmethod
+ def from_legacy(cls, event_type: str, payload: dict) -> "WorkflowEvent":
+ """Wrap a legacy Dict payload from the pre-framework dispatch path.
+
+ Used by the back-compat shim in event_waiter.dispatch so existing
+ plugins (telegram, whatsapp, gmail, etc.) keep working until they
+ migrate to native WorkflowEvent emission.
+ """
+ return cls(
+ source=f"legacy://{event_type}",
+ type=event_type,
+ data=payload,
+ )
+
+ def matches_type(self, pattern: str) -> bool:
+ """Glob-style match on event type. ``"all"``/empty matches any.
+
+ Examples:
+ "stripe.charge.succeeded" matches itself
+ "stripe.charge.*" matches "stripe.charge.succeeded"
+ "stripe.*" matches "stripe.charge.succeeded"
+ "all" or "" matches everything
+ """
+ if not pattern or pattern == "all":
+ return True
+ if pattern.endswith(".*"):
+ prefix = pattern[:-2]
+ return self.type.startswith(prefix + ".") or self.type == prefix
+ return self.type == pattern
diff --git a/server/services/events/lifecycle.py b/server/services/events/lifecycle.py
new file mode 100644
index 00000000..04928fb4
--- /dev/null
+++ b/server/services/events/lifecycle.py
@@ -0,0 +1,99 @@
+"""Generic lifecycle wiring helpers.
+
+:func:`make_lifecycle_handlers` returns the standard 4 WebSocket
+handlers (``connect`` / ``disconnect`` / ``reconnect`` / ``status``) for
+any :class:`EventSource`. Plugins call it once and register the dict —
+no per-handler boilerplate.
+
+:func:`make_status_refresh` returns a ``register_service_refresh``
+callback that auto-reconnects the source when a credential is stored
+and mirrors its status into the broadcaster cache.
+
+Together these collapse ~50 LOC of identical boilerplate per plugin
+into two function calls.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Dict, TYPE_CHECKING
+
+from fastapi import WebSocket
+
+from core.logging import get_logger
+
+from .source import EventSource
+
+if TYPE_CHECKING:
+ from services.status_broadcaster import StatusBroadcaster
+
+logger = get_logger(__name__)
+
+
+def make_lifecycle_handlers(
+ prefix: str,
+ source: EventSource,
+ *,
+ extra: Dict[str, Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]] | None = None,
+) -> Dict[str, Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]]:
+ """Return ``{prefix}_connect / _disconnect / _reconnect / _status`` handlers.
+
+ Pass ``extra`` to merge additional plugin-specific handlers (e.g.
+ ``{"stripe_trigger": handle_stripe_trigger}``).
+ """
+
+ async def _connect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ return await source.start()
+
+ async def _disconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ return await source.stop()
+
+ async def _reconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ restart = getattr(source, "restart", None)
+ if restart is not None:
+ return await restart()
+ await source.stop()
+ return await source.start()
+
+ async def _status(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ status = await source.status()
+ if hasattr(source, "has_credential"):
+ status["has_stored_key"] = await source.has_credential() # type: ignore[attr-defined]
+ return {"success": True, "status": status}
+
+ handlers: Dict[str, Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]] = {
+ f"{prefix}_connect": _connect,
+ f"{prefix}_disconnect": _disconnect,
+ f"{prefix}_reconnect": _reconnect,
+ f"{prefix}_status": _status,
+ }
+ if extra:
+ handlers.update(extra)
+ return handlers
+
+
+def make_status_refresh(
+ source: EventSource,
+ *,
+ status_key: str,
+ broadcast_type: str,
+) -> Callable[["StatusBroadcaster"], Awaitable[None]]:
+ """Return a ``register_service_refresh`` callback.
+
+ The callback auto-starts the source if it has stored credentials,
+ mirrors its status into ``broadcaster._status[status_key]``, and
+ emits a ``broadcast_type`` broadcast.
+ """
+
+ async def refresh(broadcaster: "StatusBroadcaster") -> None:
+ try:
+ if not getattr(source, "_started", False) and hasattr(source, "has_credential"):
+ if await source.has_credential(): # type: ignore[attr-defined]
+ logger.info("[StatusBroadcaster] auto-reconnecting %s", status_key)
+ await source.start()
+ status = await source.status()
+ broadcaster._status[status_key] = status
+ await broadcaster.broadcast({"type": broadcast_type, "data": status})
+ except Exception as e:
+ logger.debug("[StatusBroadcaster] %s refresh failed: %s", status_key, e)
+
+ return refresh
diff --git a/server/services/events/polling.py b/server/services/events/polling.py
new file mode 100644
index 00000000..1360a945
--- /dev/null
+++ b/server/services/events/polling.py
@@ -0,0 +1,60 @@
+"""PollingEventSource — periodic pull from an external API.
+
+Replaces the duplicated loop frame in gmail_receive.py / email_receive.py /
+twitter_receive.py. Subclasses implement :meth:`poll_once` and the
+framework owns sleep timing, baseline-state persistence, and cancellation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import AsyncIterator, ClassVar, Dict, Iterable
+
+from core.logging import get_logger
+
+from .envelope import WorkflowEvent
+from .source import EventSource
+
+logger = get_logger(__name__)
+
+
+class PollingEventSource(EventSource):
+ """Polling-mode source. Subclasses provide :meth:`poll_once`."""
+
+ poll_interval_default: ClassVar[int] = 60
+
+ def __init__(self, poll_interval: int | None = None) -> None:
+ super().__init__()
+ self.poll_interval = poll_interval or self.poll_interval_default
+ self._state: Dict = {}
+
+ async def load_state(self) -> Dict:
+ """Override to hydrate cursor / last-seen-id from disk or DB.
+ Default keeps state in-memory only (lost on restart)."""
+ return self._state
+
+ async def save_state(self, state: Dict) -> None:
+ """Override to persist cursor across restarts."""
+ self._state = state
+
+ async def poll_once(self, state: Dict) -> Iterable[WorkflowEvent]:
+ """Return any new events since the last poll. Mutate ``state``
+ in place to record what was seen."""
+ raise NotImplementedError
+
+ async def emit(self) -> AsyncIterator[WorkflowEvent]:
+ state = await self.load_state()
+ while not self._stopped:
+ try:
+ events = await self.poll_once(state) or []
+ await self.save_state(state)
+ for ev in events:
+ yield ev
+ except asyncio.CancelledError:
+ raise
+ except Exception as e:
+ logger.warning("[%s] poll_once failed: %s", self.type, e)
+ try:
+ await asyncio.sleep(self.poll_interval)
+ except asyncio.CancelledError:
+ break
diff --git a/server/services/events/push.py b/server/services/events/push.py
new file mode 100644
index 00000000..51697f04
--- /dev/null
+++ b/server/services/events/push.py
@@ -0,0 +1,36 @@
+"""PushEventSource — events arrive via external write (HTTP webhook,
+RPC callback, server-sent event). The source itself is passive: it
+exposes a :meth:`receive` method that whoever owns the inbound channel
+calls with each new payload, and an internal queue surfaces the events
+through the standard :meth:`emit` async iterator.
+
+Used directly by :class:`WebhookSource` (in webhook.py); future RPC /
+SSE sources subclass this same base.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import AsyncIterator
+
+from .envelope import WorkflowEvent
+from .source import EventSource
+
+
+class PushEventSource(EventSource):
+ """Push-mode source: external code calls :meth:`receive` with each
+ event; :meth:`emit` yields them in order.
+ """
+
+ def __init__(self) -> None:
+ super().__init__()
+ self._queue: asyncio.Queue[WorkflowEvent] = asyncio.Queue()
+
+ async def receive(self, event: WorkflowEvent) -> None:
+ """Hand-off from the inbound channel into the framework queue."""
+ await self._queue.put(event)
+
+ async def emit(self) -> AsyncIterator[WorkflowEvent]:
+ while not self._stopped:
+ event = await self._queue.get()
+ yield event
diff --git a/server/services/events/source.py b/server/services/events/source.py
new file mode 100644
index 00000000..70e6e98b
--- /dev/null
+++ b/server/services/events/source.py
@@ -0,0 +1,63 @@
+"""EventSource abstract base — every external event-producer plugs in here.
+
+Three concrete subclasses cover the four execution modalities documented
+in Apache Camel EIP and matched by n8n's trigger model:
+
+ PushEventSource HTTP webhooks, server-sent events, RPC pushes
+ PollingEventSource interval-based pull (Gmail/Twitter/IMAP polling)
+ DaemonEventSource long-lived subprocess or SDK loop (Stripe CLI,
+ Telegram bot, WhatsApp Go RPC)
+
+Cron / scheduled events stay on APScheduler — they don't need this base.
+Internal (in-process) events go through ``event_waiter.dispatch`` directly.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator, ClassVar, Dict, Optional, Type
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class EventSource(ABC):
+ """Base — subclasses declare ``type``, optionally ``credential``,
+ and implement :meth:`emit` (or one of the convenience hooks on the
+ concrete subclasses)."""
+
+ type: ClassVar[str] = ""
+ credential: ClassVar[Optional[Type]] = None
+
+ def __init__(self) -> None:
+ self._stopped = False
+ self._started = False
+
+ async def start(self) -> Dict[str, Any]:
+ """Activate the source. Idempotent. Concrete subclasses override
+ with their actual lifecycle (subprocess spawn, polling task launch,
+ webhook registration)."""
+ self._started = True
+ self._stopped = False
+ return {"success": True, "type": self.type}
+
+ async def stop(self) -> Dict[str, Any]:
+ """Deactivate. Idempotent."""
+ self._stopped = True
+ self._started = False
+ return {"success": True, "type": self.type}
+
+ async def status(self) -> Dict[str, Any]:
+ """Snapshot for the credentials modal / status broadcaster."""
+ return {"type": self.type, "running": self._started}
+
+ @abstractmethod
+ def emit(self) -> AsyncIterator:
+ """Async iterator yielding ``WorkflowEvent`` instances.
+
+ Returning an iterator (not awaiting it) lets the framework
+ manage cancellation and back-pressure uniformly across push,
+ polling, and daemon sources.
+ """
+ raise NotImplementedError
diff --git a/server/services/events/triggers.py b/server/services/events/triggers.py
new file mode 100644
index 00000000..6a5536ce
--- /dev/null
+++ b/server/services/events/triggers.py
@@ -0,0 +1,118 @@
+"""Generic TriggerNode base classes backed by EventSources.
+
+Plugins subclass :class:`WebhookTriggerNode` and declare:
+
+ type, display_name, group, ... (standard plugin metadata)
+ webhook_source: ClassVar[Type[WebhookSource]]
+ Params, Output (Pydantic models)
+ shape_output(event) (optional) reshape WorkflowEvent -> Output dict
+ _check_precondition() (optional) return error str if not ready
+ _extra_filter(params) (optional) additional filter on top of event_type
+
+The base provides:
+ - event_type derived from webhook_source.type
+ - build_filter combining CloudEvents type-glob + _extra_filter
+ - execute() with precheck + shape passthrough
+ - the standard Operation("wait") stub
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, ClassVar, Dict, Optional, Type
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from services.plugin import NodeContext, Operation, TaskQueue, TriggerNode
+
+from .envelope import WorkflowEvent
+from .webhook import WebhookSource
+
+
+class BaseTriggerParams(BaseModel):
+ """Default Params for WebhookTriggerNode subclasses. Subclass and add
+ provider-specific filters."""
+
+ event_type_filter: str = Field(
+ default="all",
+ description=(
+ "Event type to match. 'all' for every event, exact name, "
+ "or wildcard prefix (e.g. 'foo.*')."
+ ),
+ )
+
+ model_config = ConfigDict(extra="ignore")
+
+
+class WebhookTriggerNode(TriggerNode):
+ """TriggerNode whose events arrive through a :class:`WebhookSource`.
+
+ The framework owns the wait/dispatch flow; subclasses describe only
+ the differences from the generic shape.
+ """
+
+ webhook_source: ClassVar[Optional[Type[WebhookSource]]] = None
+ # Auto-prepended to ``event_type_filter`` so users can type "charge.*"
+ # instead of "stripe.charge.*". Empty disables the convenience.
+ event_type_prefix: ClassVar[str] = ""
+ mode: ClassVar[str] = "event"
+ task_queue: ClassVar[str] = TaskQueue.TRIGGERS_EVENT
+ Params: ClassVar[Type[BaseModel]] = BaseTriggerParams
+
+ def __init_subclass__(cls, **kwargs):
+ super().__init_subclass__(**kwargs)
+ if cls.webhook_source is not None and not getattr(cls, "event_type", ""):
+ cls.event_type = cls.webhook_source.type
+
+ def build_filter(self, params: BaseModel) -> Callable[[Any], bool]:
+ type_filter = (getattr(params, "event_type_filter", "") or "all").strip()
+ if (
+ type_filter
+ and type_filter != "all"
+ and self.event_type_prefix
+ and not type_filter.startswith(self.event_type_prefix)
+ ):
+ type_filter = self.event_type_prefix + type_filter
+ extras = self._extra_filter(params)
+
+ def matches(event: Any) -> bool:
+ ev = event if isinstance(event, WorkflowEvent) else WorkflowEvent(**event)
+ if not ev.matches_type(type_filter):
+ return False
+ return extras(ev) if extras else True
+
+ return matches
+
+ def _extra_filter(self, params: BaseModel) -> Optional[Callable[[WorkflowEvent], bool]]:
+ """Override for filters beyond event-type matching (e.g. livemode)."""
+ return None
+
+ async def _check_precondition(self) -> Optional[str]:
+ """Override to short-circuit. Return error string or None."""
+ return None
+
+ async def execute(
+ self,
+ node_id: str,
+ parameters: Dict[str, Any],
+ context,
+ ) -> Dict[str, Any]:
+ err = await self._check_precondition()
+ if err:
+ return self._wrap_error(start_time=time.time(), error=err)
+ result = await super().execute(node_id, parameters, context)
+ if result.get("success"):
+ event = result.get("result") or {}
+ ev = event if isinstance(event, WorkflowEvent) else WorkflowEvent(**event)
+ result["result"] = self.shape_output(ev)
+ return result
+
+ def shape_output(self, event: WorkflowEvent) -> Dict[str, Any]:
+ """Default: dump the CloudEvent. Override for provider-shaped output."""
+ return event.model_dump(mode="json")
+
+ @Operation("wait")
+ async def wait(self, ctx: NodeContext, params: BaseModel):
+ raise NotImplementedError(
+ "Event triggers return via TriggerNode.execute, not the op body"
+ )
diff --git a/server/services/events/verifiers/__init__.py b/server/services/events/verifiers/__init__.py
new file mode 100644
index 00000000..77f84faa
--- /dev/null
+++ b/server/services/events/verifiers/__init__.py
@@ -0,0 +1,25 @@
+"""Webhook signature verifiers — pluggable HMAC schemes per provider.
+
+Each verifier is a stateless class with one method:
+
+ verify(headers, body, secret) -> None # raises ValueError on mismatch
+
+Plugins reference verifier classes directly; there's no string-keyed
+registry to avoid (yet another) lookup table.
+"""
+
+from __future__ import annotations
+
+from .base import WebhookVerifier
+from .hmac_basic import HmacVerifier
+from .stripe import StripeVerifier
+from .standard_webhooks import StandardWebhooksVerifier
+from .github import GitHubVerifier
+
+__all__ = [
+ "WebhookVerifier",
+ "HmacVerifier",
+ "StripeVerifier",
+ "StandardWebhooksVerifier",
+ "GitHubVerifier",
+]
diff --git a/server/services/events/verifiers/base.py b/server/services/events/verifiers/base.py
new file mode 100644
index 00000000..4cd784f6
--- /dev/null
+++ b/server/services/events/verifiers/base.py
@@ -0,0 +1,28 @@
+"""Webhook verifier base — single-method contract."""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+
+class WebhookVerifier:
+ """Abstract base. Each provider's signature scheme is one subclass."""
+
+ @classmethod
+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+ """Raise ``ValueError`` if the request is not authentic.
+
+ ``headers`` is case-insensitive at the caller's discretion;
+ verifiers handle the lookup themselves to stay defensive.
+ ``body`` is the raw request bytes (signed payload).
+ ``secret`` is the provider-issued signing secret.
+ """
+ raise NotImplementedError
+
+ @staticmethod
+ def _header(headers: Mapping[str, str], name: str) -> str:
+ target = name.lower()
+ for k, v in headers.items():
+ if k.lower() == target:
+ return v
+ return ""
diff --git a/server/services/events/verifiers/github.py b/server/services/events/verifiers/github.py
new file mode 100644
index 00000000..674c2cca
--- /dev/null
+++ b/server/services/events/verifiers/github.py
@@ -0,0 +1,25 @@
+"""GitHub webhook signature verifier.
+
+Header: ``X-Hub-Signature-256: sha256=<hex_hmac>``
+Algorithm: HMAC-SHA256 of the secret over the raw body, hex-encoded.
+Reference: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import Mapping
+
+from .base import WebhookVerifier
+
+
+class GitHubVerifier(WebhookVerifier):
+ @classmethod
+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+ sig = cls._header(headers, "x-hub-signature-256")
+ if not sig.startswith("sha256="):
+ raise ValueError("X-Hub-Signature-256 missing or malformed")
+ expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+ if not hmac.compare_digest(expected, sig):
+ raise ValueError("X-Hub-Signature-256 mismatch")
diff --git a/server/services/events/verifiers/hmac_basic.py b/server/services/events/verifiers/hmac_basic.py
new file mode 100644
index 00000000..e66ccbce
--- /dev/null
+++ b/server/services/events/verifiers/hmac_basic.py
@@ -0,0 +1,32 @@
+"""Generic HMAC-SHA256 verifier — fallback for providers whose scheme
+is "single header carrying hex HMAC of the raw body".
+
+Subclasses customise :attr:`header_name` and (optionally)
+:attr:`signature_prefix`. The default reads ``X-Signature-256`` and
+expects a bare hex digest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import ClassVar, Mapping
+
+from .base import WebhookVerifier
+
+
+class HmacVerifier(WebhookVerifier):
+ header_name: ClassVar[str] = "X-Signature-256"
+ signature_prefix: ClassVar[str] = "" # e.g. "sha256=" for some providers
+
+ @classmethod
+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+ sig = cls._header(headers, cls.header_name)
+ if not sig:
+ raise ValueError(f"{cls.header_name} header missing")
+ if cls.signature_prefix and not sig.startswith(cls.signature_prefix):
+ raise ValueError(f"{cls.header_name} missing prefix {cls.signature_prefix!r}")
+ provided = sig[len(cls.signature_prefix):]
+ expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+ if not hmac.compare_digest(expected, provided):
+ raise ValueError(f"{cls.header_name} mismatch")
diff --git a/server/services/events/verifiers/standard_webhooks.py b/server/services/events/verifiers/standard_webhooks.py
new file mode 100644
index 00000000..6b3b0931
--- /dev/null
+++ b/server/services/events/verifiers/standard_webhooks.py
@@ -0,0 +1,47 @@
+"""Standard Webhooks (Svix) signature verifier.
+
+Spec: https://www.standardwebhooks.com/
+Headers: ``webhook-id``, ``webhook-timestamp``, ``webhook-signature``
+Signed payload: ``f"{webhook-id}.{webhook-timestamp}.{raw_body}"``
+Algorithm: HMAC-SHA256 of the secret (b64-decoded after the ``whsec_`` prefix
+is stripped) over the signed payload, base64-encoded.
+``webhook-signature`` may carry multiple space-separated ``v1,<sig>`` entries
+to support secret rotation.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+from typing import Mapping
+
+from .base import WebhookVerifier
+
+
+class StandardWebhooksVerifier(WebhookVerifier):
+ @classmethod
+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+ msg_id = cls._header(headers, "webhook-id")
+ timestamp = cls._header(headers, "webhook-timestamp")
+ sig_header = cls._header(headers, "webhook-signature")
+ if not (msg_id and timestamp and sig_header):
+ raise ValueError("Standard Webhooks headers missing")
+
+ if secret.startswith("whsec_"):
+ key = base64.b64decode(secret[len("whsec_"):])
+ else:
+ key = secret.encode()
+
+ signed = f"{msg_id}.{timestamp}.".encode() + body
+ expected = base64.b64encode(
+ hmac.new(key, signed, hashlib.sha256).digest()
+ ).decode()
+
+ candidates: list[str] = []
+ for part in sig_header.split():
+ if "," in part:
+ _, value = part.split(",", 1)
+ candidates.append(value)
+ if not any(hmac.compare_digest(expected, c) for c in candidates):
+ raise ValueError("Standard Webhooks signature mismatch")
diff --git a/server/services/events/verifiers/stripe.py b/server/services/events/verifiers/stripe.py
new file mode 100644
index 00000000..bc1c653a
--- /dev/null
+++ b/server/services/events/verifiers/stripe.py
@@ -0,0 +1,42 @@
+"""Stripe webhook signature verifier.
+
+Header format: ``Stripe-Signature: t=<unix_ts>,v1=<hex_hmac>[,v1=<rotated>]``
+Signed payload: ``f"{timestamp}.{raw_body}"`` (HMAC-SHA256, hex)
+Reference: https://stripe.com/docs/webhooks/signatures
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import Mapping
+
+from .base import WebhookVerifier
+
+
+class StripeVerifier(WebhookVerifier):
+ @classmethod
+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+ sig_header = cls._header(headers, "stripe-signature")
+ if not sig_header:
+ raise ValueError("Stripe-Signature header missing")
+
+ timestamp = ""
+ candidates: list[str] = []
+ for part in sig_header.split(","):
+ if "=" not in part:
+ continue
+ k, v = part.split("=", 1)
+ k = k.strip()
+ v = v.strip()
+ if k == "t":
+ timestamp = v
+ elif k == "v1":
+ candidates.append(v)
+ if not timestamp or not candidates:
+ raise ValueError("Stripe-Signature missing t= or v1= component")
+
+ signed = f"{timestamp}.".encode() + body
+ expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
+ if not any(hmac.compare_digest(expected, c) for c in candidates):
+ raise ValueError("Stripe-Signature mismatch")
diff --git a/server/services/events/webhook.py b/server/services/events/webhook.py
new file mode 100644
index 00000000..c06ae516
--- /dev/null
+++ b/server/services/events/webhook.py
@@ -0,0 +1,105 @@
+"""WebhookSource — push source backed by an HTTP POST to /webhook/{path}.
+
+Plugins subclass and declare:
+
+ class MyWebhook(WebhookSource):
+ path = "myprovider"
+ verifier = MyVerifier # WebhookVerifier subclass (optional)
+ secret_field = "my_webhook_secret" # extra field on the credential
+
+ async def shape(self, request, body, payload) -> WorkflowEvent: ...
+
+A single edit to ``routers/webhook.py`` consults :data:`WEBHOOK_SOURCES`
+before the legacy generic dispatch path. No plugin name is hardcoded
+in the router.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import ClassVar, Dict, Optional, Type
+
+from fastapi import HTTPException, Request
+
+from core.logging import get_logger
+
+from .envelope import WorkflowEvent
+from .push import PushEventSource
+from .verifiers import WebhookVerifier
+
+logger = get_logger(__name__)
+
+
+WEBHOOK_SOURCES: Dict[str, "WebhookSource"] = {}
+
+
+def register_webhook_source(source: "WebhookSource") -> None:
+ """Idempotent: same instance for the same path is a no-op; conflicts raise."""
+ existing = WEBHOOK_SOURCES.get(source.path)
+ if existing is not None and existing is not source:
+ raise ValueError(
+ f"Webhook path {source.path!r} already registered to {type(existing).__name__}"
+ )
+ WEBHOOK_SOURCES[source.path] = source
+
+
+class WebhookSource(PushEventSource):
+ """Base for HTTP-webhook event sources.
+
+ Subclass contract:
+ path: URL fragment under /webhook/
+ verifier: WebhookVerifier subclass (or None to skip verification)
+ secret_field: credential extra-field name holding the signing secret
+ shape(): turn the verified request into a WorkflowEvent
+ """
+
+ path: ClassVar[str] = ""
+ verifier: ClassVar[Optional[Type[WebhookVerifier]]] = None
+ secret_field: ClassVar[Optional[str]] = None
+
+ async def _resolve_secret(self) -> Optional[str]:
+ if self.secret_field is None or self.credential is None:
+ return None
+ try:
+ secrets = await self.credential.resolve()
+ except PermissionError:
+ return None
+ return secrets.get(self.secret_field)
+
+ async def shape(self, request: Request, body: bytes, payload: dict) -> WorkflowEvent:
+ """Override to map the verified payload into a CloudEvent."""
+ return WorkflowEvent(
+ source=f"webhook://{self.path}",
+ type=f"webhook.{self.path}",
+ data=payload,
+ )
+
+ async def handle(self, request: Request) -> WorkflowEvent:
+ """Called by the webhook router. Verifies signature, parses the
+ body, shapes the event, dispatches into ``event_waiter``, and
+ returns the event for logging / response shaping."""
+ body = await request.body()
+ if self.verifier is not None:
+ secret = await self._resolve_secret()
+ if not secret:
+ logger.warning(
+ "[%s] no signing secret available; accepting unverified event",
+ self.type or self.path,
+ )
+ else:
+ try:
+ self.verifier.verify(dict(request.headers), body, secret)
+ except ValueError as e:
+ raise HTTPException(status_code=400, detail=str(e))
+
+ try:
+ payload = json.loads(body.decode() or "{}")
+ except (json.JSONDecodeError, UnicodeDecodeError) as e:
+ raise HTTPException(status_code=400, detail=f"invalid JSON body: {e}")
+
+ event = await self.shape(request, body, payload)
+ await self.receive(event)
+
+ from services import event_waiter
+ event_waiter.dispatch(self.type, event)
+ return event
diff --git a/server/tests/services/test_events.py b/server/tests/services/test_events.py
new file mode 100644
index 00000000..f1f08808
--- /dev/null
+++ b/server/tests/services/test_events.py
@@ -0,0 +1,333 @@
+"""Contract tests for the generalized event-source framework."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Iterable
+from unittest.mock import patch
+
+import pytest
+
+pytestmark = pytest.mark.node_contract
+
+
+def _run(coro):
+ return asyncio.new_event_loop().run_until_complete(coro)
+
+
+# ============================================================================
+# WorkflowEvent envelope
+# ============================================================================
+
+
+class TestWorkflowEvent:
+ def test_required_fields(self):
+ from services.events import WorkflowEvent
+ ev = WorkflowEvent(source="stripe://acct_1", type="stripe.charge.succeeded")
+ assert ev.specversion == "1.0"
+ assert ev.id # uuid default
+ assert ev.datacontenttype == "application/json"
+
+ def test_round_trip_json(self):
+ from services.events import WorkflowEvent
+ ev = WorkflowEvent(
+ source="stripe://acct_1", type="stripe.charge.succeeded", data={"amount": 1000},
+ )
+ restored = WorkflowEvent.model_validate(json.loads(ev.model_dump_json()))
+ assert restored.type == ev.type
+ assert restored.data == {"amount": 1000}
+ assert restored.id == ev.id
+
+ def test_matches_type_glob(self):
+ from services.events import WorkflowEvent
+ ev = WorkflowEvent(source="stripe://x", type="stripe.charge.succeeded")
+ assert ev.matches_type("all") is True
+ assert ev.matches_type("") is True
+ assert ev.matches_type("stripe.charge.succeeded") is True
+ assert ev.matches_type("stripe.charge.*") is True
+ assert ev.matches_type("stripe.*") is True
+ assert ev.matches_type("payment_intent.*") is False
+
+ def test_from_legacy(self):
+ from services.events import WorkflowEvent
+ ev = WorkflowEvent.from_legacy("whatsapp_message_received", {"text": "hi"})
+ assert ev.type == "whatsapp_message_received"
+ assert ev.data == {"text": "hi"}
+ assert ev.source.startswith("legacy://")
+
+
+# ============================================================================
+# Verifiers
+# ============================================================================
+
+
+class TestStripeVerifier:
+ SECRET = "whsec_test"
+
+ def _sign(self, body: bytes, ts: int | None = None) -> dict:
+ ts = ts if ts is not None else int(time.time())
+ signed = f"{ts}.".encode() + body
+ sig = hmac.new(self.SECRET.encode(), signed, hashlib.sha256).hexdigest()
+ return {"Stripe-Signature": f"t={ts},v1={sig}"}
+
+ def test_valid_signature_passes(self):
+ from services.events import StripeVerifier
+ body = b'{"id":"evt_1"}'
+ StripeVerifier.verify(self._sign(body), body, self.SECRET)
+
+ def test_tampered_body_rejected(self):
+ from services.events import StripeVerifier
+ body = b'{"id":"evt_1"}'
+ headers = self._sign(body)
+ with pytest.raises(ValueError):
+ StripeVerifier.verify(headers, b'{"id":"evt_2"}', self.SECRET)
+
+ def test_missing_header_rejected(self):
+ from services.events import StripeVerifier
+ with pytest.raises(ValueError, match="missing"):
+ StripeVerifier.verify({}, b'{}', self.SECRET)
+
+ def test_malformed_header_rejected(self):
+ from services.events import StripeVerifier
+ with pytest.raises(ValueError):
+ StripeVerifier.verify({"Stripe-Signature": "garbage"}, b'{}', self.SECRET)
+
+
+class TestGitHubVerifier:
+ def test_round_trip(self):
+ from services.events import GitHubVerifier
+ secret = "shh"
+ body = b'{"action":"opened"}'
+ sig = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+ GitHubVerifier.verify({"X-Hub-Signature-256": sig}, body, secret)
+
+ def test_tampered_rejected(self):
+ from services.events import GitHubVerifier
+ with pytest.raises(ValueError):
+ GitHubVerifier.verify({"X-Hub-Signature-256": "sha256=deadbeef"}, b'{}', "shh")
+
+
+class TestStandardWebhooksVerifier:
+ def test_round_trip(self):
+ from services.events import StandardWebhooksVerifier
+ secret_raw = b"super-secret-key-bytes"
+ secret = "whsec_" + base64.b64encode(secret_raw).decode()
+ body = b'{"foo":"bar"}'
+ msg_id = "msg_abc"
+ ts = "1700000000"
+ signed = f"{msg_id}.{ts}.".encode() + body
+ sig = base64.b64encode(hmac.new(secret_raw, signed, hashlib.sha256).digest()).decode()
+ headers = {
+ "webhook-id": msg_id,
+ "webhook-timestamp": ts,
+ "webhook-signature": f"v1,{sig}",
+ }
+ StandardWebhooksVerifier.verify(headers, body, secret)
+
+ def test_tampered_rejected(self):
+ from services.events import StandardWebhooksVerifier
+ with pytest.raises(ValueError):
+ StandardWebhooksVerifier.verify(
+ {"webhook-id": "1", "webhook-timestamp": "1", "webhook-signature": "v1,bad"},
+ b'{}', "whsec_AAAA",
+ )
+
+
+class TestHmacVerifier:
+ def test_round_trip(self):
+ from services.events import HmacVerifier
+ secret = "shh"
+ body = b'{"x":1}'
+ sig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+ HmacVerifier.verify({"X-Signature-256": sig}, body, secret)
+
+
+# ============================================================================
+# PollingEventSource loop
+# ============================================================================
+
+
+class TestPollingEventSource:
+ def test_emits_what_poll_once_returns_then_sleeps(self):
+ from services.events import PollingEventSource, WorkflowEvent
+
+ class FakePolling(PollingEventSource):
+ type = "fake.polling"
+ poll_interval_default = 0 # tight loop for the test
+
+ def __init__(self):
+ super().__init__()
+ self.calls = 0
+
+ async def poll_once(self, state) -> Iterable[WorkflowEvent]:
+ self.calls += 1
+ if self.calls == 1:
+ return [WorkflowEvent(source="x", type="fake.tick", data={"n": 1})]
+ self._stopped = True
+ return []
+
+ async def drain():
+ src = FakePolling()
+ seen = []
+ async for ev in src.emit():
+ seen.append(ev)
+ if len(seen) >= 1:
+ src._stopped = True
+ return seen
+
+ events = _run(drain())
+ assert len(events) == 1
+ assert events[0].type == "fake.tick"
+
+
+# ============================================================================
+# WebhookSource — handle() integration
+# ============================================================================
+
+
+class TestWebhookSourceHandle:
+ def _build_source(self, secret_value: str | None):
+ from services.events import StripeVerifier, WebhookSource, WorkflowEvent
+
+ class _Cred:
+ @classmethod
+ async def resolve(cls):
+ if secret_value is None:
+ raise PermissionError
+ return {"api_key": "sk_test", "test_secret": secret_value}
+
+ class FakeSource(WebhookSource):
+ type = "fake.hook"
+ path = "fake"
+ verifier = StripeVerifier
+ secret_field = "test_secret"
+ credential = _Cred
+
+ async def shape(self, request, body, payload):
+ return WorkflowEvent(source="fake://x", type="fake.event", data=payload)
+
+ return FakeSource()
+
+ def _signed_request(self, body: bytes, secret: str):
+ ts = int(time.time())
+ signed = f"{ts}.".encode() + body
+ sig = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
+
+ class FakeReq:
+ headers = {"Stripe-Signature": f"t={ts},v1={sig}"}
+
+ async def body(self):
+ return body
+
+ return FakeReq()
+
+ def test_valid_signature_dispatches(self):
+ src = self._build_source(secret_value="whsec_test")
+ body = b'{"event":"payload"}'
+ req = self._signed_request(body, "whsec_test")
+ with patch("services.event_waiter.dispatch") as dispatch:
+ ev = _run(src.handle(req))
+ assert ev.type == "fake.event"
+ dispatch.assert_called_once()
+ called_type, called_event = dispatch.call_args[0]
+ assert called_type == "fake.hook"
+ assert called_event is ev
+
+ def test_tampered_signature_raises_400(self):
+ from fastapi import HTTPException
+ src = self._build_source(secret_value="whsec_test")
+ body = b'{"event":"payload"}'
+ req = self._signed_request(body, "whsec_other") # signed with different secret
+ with pytest.raises(HTTPException) as exc:
+ _run(src.handle(req))
+ assert exc.value.status_code == 400
+
+ def test_missing_secret_accepts_unverified(self):
+ """No secret captured yet -> log warning, accept event."""
+ src = self._build_source(secret_value=None)
+ body = b'{"event":"payload"}'
+
+ class FakeReq:
+ headers = {}
+
+ async def body(self):
+ return body
+
+ with patch("services.event_waiter.dispatch") as dispatch:
+ ev = _run(src.handle(FakeReq()))
+ assert ev.type == "fake.event"
+ dispatch.assert_called_once()
+
+
+# ============================================================================
+# DaemonEventSource lifecycle (mocked ProcessService)
+# ============================================================================
+
+
+class TestDaemonEventSource:
+ def test_start_calls_process_service_start(self):
+ from services.events import DaemonEventSource
+
+ class FakeDaemon(DaemonEventSource):
+ type = "fake.daemon"
+ process_name = "fake-daemon"
+ binary_name = "echo" # always on PATH
+
+ def build_command(self, secrets):
+ return "echo hello"
+
+ def parse_line(self, stream, line):
+ return None
+
+ async def go():
+ with patch("services.events.daemon.shutil.which", return_value="/usr/bin/echo"), \
+ patch("services.events.daemon.get_process_service") as get_ps:
+ ps = get_ps.return_value
+
+ async def fake_start(**kwargs):
+ return {"success": True, "result": {"pid": 4242}}
+
+ ps.start.side_effect = fake_start
+
+ async def fake_stop(**kwargs):
+ return {"success": True}
+
+ ps.stop.side_effect = fake_stop
+
+ src = FakeDaemon()
+ result = await src.start()
+ assert result["success"] is True
+ assert src.pid == 4242
+ ps.start.assert_called_once()
+ # Cancel the tail task so the test exits cleanly.
+ await src.stop()
+ assert src.pid is None
+
+ _run(go())
+
+ def test_start_fails_when_binary_missing(self):
+ from services.events import DaemonEventSource
+
+ class FakeDaemon(DaemonEventSource):
+ type = "fake.daemon"
+ process_name = "fake-daemon"
+ binary_name = "definitely-not-on-path-zzzzz"
+ install_hint = "see docs"
+
+ def build_command(self, secrets):
+ return "x"
+
+ async def go():
+ with patch("services.events.daemon.shutil.which", return_value=None):
+ src = FakeDaemon()
+ result = await src.start()
+ assert result["success"] is False
+ assert "PATH" in result["error"]
+ assert "see docs" in result["error"]
+
+ _run(go())