pyworkflow-engine 0.1.7__py3-none-any.whl

pyworkflow/primitives/define_hook.py

@@ -0,0 +1,150 @@
+"""
+Typed hooks with Pydantic validation.
+
+Provides a type-safe way to define hooks with validated payloads.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from pyworkflow.primitives.hooks import hook
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class TypedHook(Generic[T]):
+    """
+    A hook that validates payload against a Pydantic schema.
+
+    Provides type-safe access to hook payloads with automatic validation.
+    Token is auto-generated in format "run_id:hook_id".
+
+    Example:
+        class ApprovalPayload(BaseModel):
+            approved: bool
+            reviewer: str
+            comments: Optional[str] = None
+
+        approval = define_hook("approval", ApprovalPayload)
+
+        # In workflow - result is typed as ApprovalPayload
+        result = await approval()
+        if result.approved:
+            await process_order(order_id)
+    """
+
+    def __init__(self, name: str, schema: type[T]) -> None:
+        """
+        Initialize a typed hook.
+
+        Args:
+            name: Hook name for logging/debugging
+            schema: Pydantic model class for payload validation
+        """
+        self.name = name
+        self.schema = schema
+
+    async def __call__(
+        self,
+        *,
+        timeout: str | int | None = None,
+        on_created: Callable[[str], Awaitable[None]] | None = None,
+    ) -> T:
+        """
+        Wait for external event and validate payload.
+
+        Args:
+            timeout: Optional maximum wait time:
+                - str: Duration string ("24h", "7d")
+                - int: Seconds
+                - None: Wait forever
+            on_created: Optional async callback invoked with the token when
+                the hook is created. Use this to notify external systems.
+
+        Returns:
+            Validated payload as the Pydantic model type
+
+        Raises:
+            ValidationError: If payload doesn't match schema
+            RuntimeError: If called outside a workflow context
+        """
+        payload = await hook(
+            self.name,
+            timeout=timeout,
+            on_created=on_created,
+            payload_schema=self.schema,
+        )
+
+        # Validate and return typed result
+        return self.schema.model_validate(payload)
+
+    def __repr__(self) -> str:
+        return f"TypedHook(name={self.name!r}, schema={self.schema.__name__})"
+
+
+def define_hook(name: str, schema: type[T]) -> TypedHook[T]:
+    """
+    Create a typed hook with Pydantic validation.
+
+    This is the recommended way to create hooks when you want
+    type-safe, validated payloads. Token is auto-generated in
+    format "run_id:hook_id".
+
+    Args:
+        name: Hook name for logging/debugging
+        schema: Pydantic model class for payload validation
+
+    Returns:
+        TypedHook instance that can be awaited in workflows
+
+    Example:
+        # Define payload schema
+        class PaymentConfirmation(BaseModel):
+            transaction_id: str
+            amount: Decimal
+            status: Literal["success", "failed"]
+            timestamp: datetime
+
+        # Create typed hook
+        payment_confirmation = define_hook("payment", PaymentConfirmation)
+
+        # Use in workflow
+        @workflow
+        async def payment_workflow(order_id: str):
+            # Send payment request...
+
+            # Wait for payment confirmation (typed!)
+            async def notify_payment_system(token: str):
+                await send_webhook_url(f"/webhook/payment/{token}")
+
+            result: PaymentConfirmation = await payment_confirmation(
+                timeout="1h",
+                on_created=notify_payment_system,
+            )
+
+            if result.status == "success":
+                return {"order_id": order_id, "paid": True}
+            else:
+                return {"order_id": order_id, "paid": False}
+    """
+    return TypedHook(name, schema)
+
+
+class HookValidationError(Exception):
+    """Raised when hook payload validation fails."""
+
+    def __init__(
+        self,
+        hook_name: str,
+        schema: type[BaseModel],
+        validation_error: ValidationError,
+    ) -> None:
+        self.hook_name = hook_name
+        self.schema = schema
+        self.validation_error = validation_error
+        super().__init__(
+            f"Hook '{hook_name}' payload validation failed for schema "
+            f"'{schema.__name__}': {validation_error}"
+        )

pyworkflow/primitives/hooks.py

@@ -0,0 +1,97 @@
+"""
+Hook primitive for waiting on external events.
+
+Allows workflows to suspend and wait for external events such as
+webhooks, manual approvals, or third-party callbacks.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from loguru import logger
+from pydantic import BaseModel
+
+from pyworkflow.context import get_context, has_context
+
+
+async def hook(
+    name: str,
+    *,
+    timeout: str | int | None = None,
+    on_created: Callable[[str], Awaitable[None]] | None = None,
+    payload_schema: type[BaseModel] | None = None,
+) -> Any:
+    """
+    Wait for an external event (webhook, approval, callback).
+
+    The workflow suspends until resume_hook() is called with the token.
+    Token is auto-generated in format "run_id:hook_id".
+
+    Different contexts handle hooks differently:
+    - MockContext: Returns mock payload immediately (configurable)
+    - LocalContext (durable): Event-sourced hook with storage
+    - LocalContext (transient): Raises NotImplementedError
+
+    Args:
+        name: Human-readable name for the hook (for logging/debugging)
+        timeout: Optional maximum wait time:
+            - str: Duration string ("24h", "7d")
+            - int: Seconds
+            - None: Wait forever
+        on_created: Optional async callback invoked with the token when
+            the hook is created. Use this to notify external systems.
+        payload_schema: Optional Pydantic model class for payload validation.
+            When provided, the schema is stored with the hook for CLI resume.
+
+    Returns:
+        Payload from resume_hook()
+
+    Raises:
+        RuntimeError: If called outside a workflow context
+        NotImplementedError: If context doesn't support hooks
+
+    Examples:
+        # Simple hook with auto-generated token
+        payload = await hook("approval")
+
+        # With callback to notify external system
+        async def notify_approver(token: str):
+            await send_email(f"Approve at /webhook/{token}")
+
+        payload = await hook("approval", on_created=notify_approver)
+
+        # With timeout
+        payload = await hook("approval", timeout="24h")
+    """
+    if not has_context():
+        raise RuntimeError(
+            "hook() must be called within a workflow context. "
+            "Make sure you're using the @workflow decorator."
+        )
+
+    ctx = get_context()
+
+    # Parse timeout to seconds
+    timeout_seconds: int | None = None
+    if timeout is not None:
+        if isinstance(timeout, str):
+            from pyworkflow.utils.duration import parse_duration
+
+            timeout_seconds = parse_duration(timeout)
+        else:
+            timeout_seconds = int(timeout)
+
+    logger.debug(
+        f"Hook '{name}' via {ctx.__class__.__name__}",
+        run_id=ctx.run_id,
+        workflow_name=ctx.workflow_name,
+    )
+
+    # Call the context's hook method
+    # Token is auto-generated by context, on_created is called before suspension
+    return await ctx.hook(
+        name,
+        timeout=timeout_seconds,
+        on_created=on_created,
+        payload_schema=payload_schema,
+    )

pyworkflow/primitives/resume_hook.py

@@ -0,0 +1,210 @@
+"""
+Resume hook primitive for external event delivery.
+
+Allows external systems to deliver payloads to suspended workflows.
+Uses events for idempotency checks (no separate hook storage needed).
+"""
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from loguru import logger
+
+from pyworkflow.core.exceptions import (
+    HookAlreadyReceivedError,
+    HookExpiredError,
+    HookNotFoundError,
+    InvalidTokenError,
+)
+from pyworkflow.engine.events import EventType
+from pyworkflow.storage.base import StorageBackend
+
+# Token format separator
+HOOK_TOKEN_SEPARATOR = ":"
+
+
+def parse_hook_token(token: str) -> tuple[str, str]:
+    """
+    Parse a composite hook token into run_id and hook_id.
+
+    Args:
+        token: Composite token in format "run_id:hook_id"
+
+    Returns:
+        Tuple of (run_id, hook_id)
+
+    Raises:
+        InvalidTokenError: If token format is invalid
+    """
+    parts = token.split(HOOK_TOKEN_SEPARATOR, 1)
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise InvalidTokenError(f"Invalid token format: {token}")
+    return parts[0], parts[1]
+
+
+def create_hook_token(run_id: str, hook_id: str) -> str:
+    """
+    Create a composite hook token from run_id and hook_id.
+
+    Args:
+        run_id: The workflow run ID
+        hook_id: The hook ID
+
+    Returns:
+        Composite token in format "run_id:hook_id"
+    """
+    return f"{run_id}{HOOK_TOKEN_SEPARATOR}{hook_id}"
+
+
+@dataclass
+class ResumeResult:
+    """Result of a resume_hook operation."""
+
+    run_id: str
+    hook_id: str
+    status: str  # "resumed", "already_received", "expired", "not_found"
+
+    def __repr__(self) -> str:
+        return f"ResumeResult(run_id={self.run_id!r}, hook_id={self.hook_id!r}, status={self.status!r})"
+
+
+async def resume_hook(
+    token: str,
+    payload: Any,
+    *,
+    storage: StorageBackend | None = None,
+) -> ResumeResult:
+    """
+    Resume a suspended workflow with a payload.
+
+    This function is called by external systems (webhooks, APIs, etc.)
+    to deliver data to a waiting workflow.
+
+    Idempotency is checked via events:
+    - HOOK_CREATED event must exist for the hook_id
+    - HOOK_RECEIVED event must not exist (would mean already resumed)
+
+    Args:
+        token: The hook token (composite format: run_id:hook_id)
+        payload: Data to send to the workflow
+        storage: Storage backend. If None, uses the configured default.
+
+    Returns:
+        ResumeResult with run_id, hook_id, and status
+
+    Raises:
+        InvalidTokenError: If the token format is invalid
+        HookNotFoundError: If no hook exists with the given token
+        HookExpiredError: If the hook has expired
+        HookAlreadyReceivedError: If the hook was already resumed
+
+    Examples:
+        # In a FastAPI endpoint
+        @app.post("/webhook/{token}")
+        async def handle_webhook(token: str, payload: dict):
+            result = await resume_hook(token, payload)
+            return {"run_id": result.run_id, "status": result.status}
+
+        # With explicit storage
+        result = await resume_hook(
+            token="run_abc123:hook_approval_1",
+            payload={"approved": True},
+            storage=my_storage,
+        )
+    """
+    # Get storage backend
+    if storage is None:
+        from pyworkflow import get_storage
+
+        storage = get_storage()
+
+    if storage is None:
+        raise RuntimeError(
+            "No storage backend configured. "
+            "Either pass storage parameter or call pyworkflow.configure(storage=...)"
+        )
+
+    # Parse token to get run_id and hook_id
+    run_id, hook_id = parse_hook_token(token)
+
+    # Get all events for this run to check hook status
+    events = await storage.get_events(run_id)
+
+    # Find HOOK_CREATED event for this hook_id
+    hook_created_event = None
+    hook_received_event = None
+
+    for event in events:
+        if event.type == EventType.HOOK_CREATED:
+            if event.data.get("hook_id") == hook_id:
+                hook_created_event = event
+        elif event.type == EventType.HOOK_RECEIVED and event.data.get("hook_id") == hook_id:
+            hook_received_event = event
+
+    # Check if hook was created
+    if hook_created_event is None:
+        logger.warning(f"Hook not found: {hook_id} (run_id={run_id})")
+        raise HookNotFoundError(token)
+
+    # Check if already received (idempotency check)
+    if hook_received_event is not None:
+        logger.warning(f"Hook already received: {hook_id}")
+        raise HookAlreadyReceivedError(hook_id)
+
+    # Check expiration
+    expires_at_str = hook_created_event.data.get("expires_at")
+    if expires_at_str:
+        expires_at = datetime.fromisoformat(expires_at_str)
+        if datetime.now(UTC) > expires_at:
+            logger.warning(f"Hook expired: {hook_id}")
+            raise HookExpiredError(hook_id)
+
+    logger.info(
+        f"Resuming hook: {hook_id}",
+        run_id=run_id,
+        hook_id=hook_id,
+    )
+
+    # Record HOOK_RECEIVED event (this is the idempotency marker and payload store)
+    from pyworkflow.engine.events import create_hook_received_event
+    from pyworkflow.serialization.encoder import serialize
+    from pyworkflow.storage.schemas import HookStatus
+
+    serialized_payload = serialize(payload)
+
+    event = create_hook_received_event(
+        run_id=run_id,
+        hook_id=hook_id,
+        payload=serialized_payload,
+    )
+    await storage.record_event(event)
+
+    # Update hook status in storage
+    await storage.update_hook_status(
+        hook_id=hook_id,
+        status=HookStatus.RECEIVED,
+        payload=serialized_payload,
+    )
+
+    # Schedule workflow resumption via configured runtime
+    from pyworkflow.config import get_config
+    from pyworkflow.runtime import get_runtime
+
+    config = get_config()
+    runtime = get_runtime(config.default_runtime)
+
+    try:
+        await runtime.schedule_resume(run_id, storage)
+    except Exception as e:
+        logger.warning(
+            f"Failed to schedule workflow resumption: {e}",
+            run_id=run_id,
+            hook_id=hook_id,
+        )
+
+    return ResumeResult(
+        run_id=run_id,
+        hook_id=hook_id,
+        status="resumed",
+    )