Skip to content

Self-improving AI Employees for everyone

4.9 KB
Raw Blame
"""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)
        # The canvas Run's waiter key. A source whose ``shape`` returns
        # envelopes of another type must have its trigger set ``event_type``
        # to that type, or ``event_waiter.dispatch`` matches no waiter.
        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"):
            result["result"] = self.shape_output(self._as_event(result.get("result")))
        return result

    def _as_event(self, value: Any) -> WorkflowEvent:
        """Wrap what a resolved waiter returns back into an envelope.

        The event waiter resolves with the envelope's ``data``, not the
        envelope (``event_waiter._unpack_event``). Rebuilding a
        ``WorkflowEvent`` from that dict raised, because a payload carries no
        ``source`` or ``type``.
        """
        if isinstance(value, WorkflowEvent):
            return value
        path = self.webhook_source.path if self.webhook_source is not None else ""
        return WorkflowEvent(source=f"webhook://{path}", type=self.event_type, data=value or {})

    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")