pyworkflow-engine 0.1.7__py3-none-any.whl

pyworkflow/engine/replay.py

@@ -0,0 +1,273 @@
+"""
+Event replay engine for deterministic workflow state reconstruction.
+
+The replay engine processes the event log to rebuild workflow state,
+enabling fault tolerance and resumption after crashes or suspensions.
+"""
+
+from loguru import logger
+
+from pyworkflow.context import LocalContext
+from pyworkflow.engine.events import Event, EventType
+
+
+class EventReplayer:
+    """
+    Replays events to reconstruct workflow state.
+
+    The replayer processes events in sequence order to restore:
+    - Completed step results
+    - Hook payloads
+    - Sleep completion status
+    """
+
+    async def replay(self, ctx: LocalContext, events: list[Event]) -> None:
+        """
+        Replay events to restore workflow state.
+
+        This enables deterministic execution - same events always produce
+        same state.
+
+        Args:
+            ctx: Workflow context to populate
+            events: List of events ordered by sequence
+        """
+        if not events:
+            logger.debug(f"No events to replay for run {ctx.run_id}")
+            return
+
+        logger.debug(
+            f"Replaying {len(events)} events for run {ctx.run_id}",
+            run_id=ctx.run_id,
+            workflow_name=ctx.workflow_name,
+        )
+
+        ctx.is_replaying = True
+        ctx.event_log = events
+
+        for event in sorted(events, key=lambda e: e.sequence or 0):
+            await self._apply_event(ctx, event)
+
+        ctx.is_replaying = False
+
+        logger.debug(
+            f"Replay complete: {len(ctx.step_results)} steps, "
+            f"{len(ctx.hook_results)} hooks, "
+            f"{len(ctx.pending_sleeps)} pending sleeps, "
+            f"{len(ctx.retry_state)} pending retries",
+            run_id=ctx.run_id,
+        )
+
+    async def _apply_event(self, ctx: LocalContext, event: Event) -> None:
+        """
+        Apply a single event to the context.
+
+        Args:
+            ctx: Workflow context
+            event: Event to apply
+        """
+        if event.type == EventType.STEP_COMPLETED:
+            await self._apply_step_completed(ctx, event)
+
+        elif event.type == EventType.SLEEP_STARTED:
+            await self._apply_sleep_started(ctx, event)
+
+        elif event.type == EventType.SLEEP_COMPLETED:
+            await self._apply_sleep_completed(ctx, event)
+
+        elif event.type == EventType.HOOK_CREATED:
+            await self._apply_hook_created(ctx, event)
+
+        elif event.type == EventType.HOOK_RECEIVED:
+            await self._apply_hook_received(ctx, event)
+
+        elif event.type == EventType.HOOK_EXPIRED:
+            await self._apply_hook_expired(ctx, event)
+
+        elif event.type == EventType.STEP_RETRYING:
+            await self._apply_step_retrying(ctx, event)
+
+        elif event.type == EventType.WORKFLOW_INTERRUPTED:
+            await self._apply_workflow_interrupted(ctx, event)
+
+        elif event.type == EventType.CANCELLATION_REQUESTED:
+            await self._apply_cancellation_requested(ctx, event)
+
+        # Other event types don't affect replay state
+        # (workflow_started, step_started, step_failed, etc. are informational)
+
+    async def _apply_step_completed(self, ctx: LocalContext, event: Event) -> None:
+        """Apply step_completed event - cache the result."""
+        from pyworkflow.serialization.decoder import deserialize
+
+        step_id = event.data.get("step_id")
+        result_json = event.data.get("result")
+
+        if step_id and result_json:
+            # Deserialize the result before caching
+            result = deserialize(result_json)
+            ctx.cache_step_result(step_id, result)
+            logger.debug(
+                f"Cached step result: {step_id}",
+                run_id=ctx.run_id,
+                step_id=step_id,
+            )
+
+    async def _apply_sleep_started(self, ctx: LocalContext, event: Event) -> None:
+        """Apply sleep_started event - mark sleep as pending."""
+        from datetime import datetime
+
+        sleep_id = event.data.get("sleep_id")
+        resume_at_str = event.data.get("resume_at")
+
+        if sleep_id and resume_at_str:
+            # Parse resume_at from ISO format
+            resume_at = datetime.fromisoformat(resume_at_str)
+            ctx.add_pending_sleep(sleep_id, resume_at)
+            logger.debug(
+                f"Sleep pending: {sleep_id}",
+                run_id=ctx.run_id,
+                sleep_id=sleep_id,
+                resume_at=resume_at_str,
+            )
+
+    async def _apply_sleep_completed(self, ctx: LocalContext, event: Event) -> None:
+        """Apply sleep_completed event - mark sleep as done."""
+        sleep_id = event.data.get("sleep_id")
+
+        if sleep_id:
+            ctx.mark_sleep_completed(sleep_id)
+            logger.debug(
+                f"Sleep completed: {sleep_id}",
+                run_id=ctx.run_id,
+                sleep_id=sleep_id,
+            )
+
+    async def _apply_hook_created(self, ctx: LocalContext, event: Event) -> None:
+        """Apply hook_created event - mark hook as pending."""
+        hook_id = event.data.get("hook_id")
+
+        if hook_id:
+            ctx.add_pending_hook(hook_id, event.data)
+            logger.debug(
+                f"Hook pending: {hook_id}",
+                run_id=ctx.run_id,
+                hook_id=hook_id,
+            )
+
+    async def _apply_hook_received(self, ctx: LocalContext, event: Event) -> None:
+        """Apply hook_received event - cache the payload."""
+        hook_id = event.data.get("hook_id")
+        payload = event.data.get("payload")
+
+        if hook_id:
+            ctx.cache_hook_result(hook_id, payload)
+            logger.debug(
+                f"Cached hook result: {hook_id}",
+                run_id=ctx.run_id,
+                hook_id=hook_id,
+            )
+
+    async def _apply_hook_expired(self, ctx: LocalContext, event: Event) -> None:
+        """Apply hook_expired event - remove from pending."""
+        hook_id = event.data.get("hook_id")
+
+        if hook_id:
+            ctx.pending_hooks.pop(hook_id, None)
+            logger.debug(
+                f"Hook expired: {hook_id}",
+                run_id=ctx.run_id,
+                hook_id=hook_id,
+            )
+
+    async def _apply_step_retrying(self, ctx: LocalContext, event: Event) -> None:
+        """Apply step_retrying event - restore retry state for resumption."""
+        from datetime import datetime
+
+        step_id = event.data.get("step_id")
+        next_attempt = event.data.get("attempt")
+        resume_at_str = event.data.get("resume_at")
+        event.data.get("retry_after")
+        max_retries = event.data.get("max_retries", 3)
+        retry_delay = event.data.get("retry_strategy", "exponential")
+        last_error = event.data.get("error", "")
+
+        if step_id and next_attempt:
+            # Parse resume_at from ISO format
+            resume_at = datetime.fromisoformat(resume_at_str) if resume_at_str else None
+
+            # Restore retry state to context
+            ctx.set_retry_state(
+                step_id=step_id,
+                attempt=next_attempt,
+                resume_at=resume_at,
+                max_retries=max_retries,
+                retry_delay=retry_delay,
+                last_error=last_error,
+            )
+
+            logger.debug(
+                f"Retry pending: {step_id}",
+                run_id=ctx.run_id,
+                step_id=step_id,
+                next_attempt=next_attempt,
+                resume_at=resume_at_str,
+            )
+
+    async def _apply_workflow_interrupted(self, ctx: LocalContext, event: Event) -> None:
+        """
+        Apply workflow_interrupted event - log the interruption.
+
+        This event is informational for the replay - it doesn't change state
+        since the workflow will continue from the last completed step.
+        The event records that an interruption occurred for auditing purposes.
+        """
+        reason = event.data.get("reason", "unknown")
+        recovery_attempt = event.data.get("recovery_attempt", 0)
+        last_event_sequence = event.data.get("last_event_sequence")
+
+        logger.info(
+            f"Workflow was interrupted: {reason}",
+            run_id=ctx.run_id,
+            reason=reason,
+            recovery_attempt=recovery_attempt,
+            last_event_sequence=last_event_sequence,
+        )
+
+    async def _apply_cancellation_requested(self, ctx: LocalContext, event: Event) -> None:
+        """
+        Apply cancellation_requested event - mark workflow for cancellation.
+
+        This event signals that cancellation was requested. During replay,
+        we set the cancellation flag so the workflow will raise CancellationError
+        at the next check point.
+        """
+        reason = event.data.get("reason")
+        requested_by = event.data.get("requested_by")
+
+        # Set cancellation flag in context
+        ctx.request_cancellation(reason=reason)
+
+        logger.info(
+            "Cancellation requested for workflow",
+            run_id=ctx.run_id,
+            reason=reason,
+            requested_by=requested_by,
+        )
+
+
+# Singleton instance
+_replayer = EventReplayer()
+
+
+async def replay_events(ctx: LocalContext, events: list[Event]) -> None:
+    """
+    Replay events to restore workflow state.
+
+    Public API for event replay.
+
+    Args:
+        ctx: Workflow context to populate
+        events: List of events to replay
+    """
+    await _replayer.replay(ctx, events)

pyworkflow/observability/__init__.py

@@ -0,0 +1,19 @@
+"""
+Observability and logging for PyWorkflow.
+
+Provides structured logging, metrics, and tracing capabilities for workflows.
+"""
+
+from pyworkflow.observability.logging import (
+    bind_step_context,
+    bind_workflow_context,
+    configure_logging,
+    get_logger,
+)
+
+__all__ = [
+    "configure_logging",
+    "get_logger",
+    "bind_workflow_context",
+    "bind_step_context",
+]

pyworkflow/observability/logging.py

@@ -0,0 +1,234 @@
+"""
+Loguru logging configuration for PyWorkflow.
+
+Provides structured logging with context-aware formatting for workflows, steps,
+and events. Integrates with loguru for powerful logging capabilities.
+"""
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+
+def configure_logging(
+    level: str = "INFO",
+    log_file: str | None = None,
+    json_logs: bool = False,
+    show_context: bool = True,
+) -> None:
+    """
+    Configure PyWorkflow logging with loguru.
+
+    This sets up structured logging with workflow context (run_id, step_id, etc.)
+    and flexible output formats.
+
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_file: Optional file path for log output
+        json_logs: If True, output logs in JSON format (useful for production)
+        show_context: If True, include workflow context in log messages
+
+    Examples:
+        # Basic configuration (console output only)
+        configure_logging()
+
+        # Debug mode with file output
+        configure_logging(level="DEBUG", log_file="workflow.log")
+
+        # Production mode with JSON logs
+        configure_logging(
+            level="INFO",
+            log_file="production.log",
+            json_logs=True
+        )
+
+        # Minimal logs without context
+        configure_logging(level="WARNING", show_context=False)
+    """
+    # Remove default logger
+    logger.remove()
+
+    # Console format
+    if json_logs:
+        # JSON format for structured logging
+        console_format = _get_json_format()
+    else:
+        # Human-readable format
+        if show_context:
+            # Include extra context when available (run_id, step_id, etc.)
+            console_format = (
+                "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+                "<level>{level: <8}</level> | "
+                "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
+                "<level>{message}</level>"
+            )
+        else:
+            console_format = (
+                "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+                "<level>{level: <8}</level> | "
+                "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+                "<level>{message}</level>"
+            )
+
+    # Add console handler with filter to inject context
+    def format_with_context(record: dict[str, Any]) -> bool:
+        """Add context fields to the format string dynamically."""
+        extra_str = ""
+        if show_context and record["extra"]:
+            # Build context string from extra fields
+            context_parts = []
+            if "run_id" in record["extra"]:
+                context_parts.append(f"run_id={record['extra']['run_id']}")
+            if "step_id" in record["extra"]:
+                context_parts.append(f"step_id={record['extra']['step_id']}")
+            if "workflow_name" in record["extra"]:
+                context_parts.append(f"workflow={record['extra']['workflow_name']}")
+            if context_parts:
+                extra_str = " | " + " ".join(context_parts)
+        record["extra"]["_context"] = extra_str
+        return True
+
+    logger.add(
+        sys.stderr,
+        format=console_format + "{extra[_context]}",
+        level=level,
+        colorize=not json_logs,
+        serialize=json_logs,
+        filter=format_with_context,  # type: ignore[arg-type]
+    )
+
+    # Add file handler if requested
+    if log_file:
+        log_path = Path(log_file)
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if json_logs:
+            # JSON format for file
+            logger.add(
+                log_file,
+                format=_get_json_format(),
+                level=level,
+                rotation="100 MB",
+                retention="30 days",
+                compression="gz",
+                serialize=True,
+            )
+        else:
+            # Human-readable format for file
+            logger.add(
+                log_file,
+                format=(
+                    "{time:YYYY-MM-DD HH:mm:ss.SSS} | "
+                    "{level: <8} | "
+                    "{name}:{function}:{line} | "
+                    "{message} | "
+                    "{extra}"
+                ),
+                level=level,
+                rotation="100 MB",
+                retention="30 days",
+                compression="gz",
+            )
+
+    logger.info(f"PyWorkflow logging configured at level {level}")
+
+
+def _get_json_format() -> str:
+    """
+    Get JSON log format string.
+
+    Returns:
+        Format string for JSON structured logging
+    """
+    return (
+        '{{"timestamp":"{time:YYYY-MM-DD HH:mm:ss.SSS}",'
+        '"level":"{level}",'
+        '"logger":"{name}",'
+        '"function":"{function}",'
+        '"line":{line},'
+        '"message":"{message}",'
+        '"extra":{extra}}}'
+    )
+
+
+def get_logger(name: str | None = None) -> Any:
+    """
+    Get a logger instance.
+
+    This is a convenience function that returns the configured loguru logger
+    with optional context binding.
+
+    Args:
+        name: Optional logger name (for filtering)
+
+    Returns:
+        Configured logger instance
+
+    Examples:
+        # Get logger for a module
+        log = get_logger(__name__)
+        log.info("Processing workflow")
+
+        # Use with context
+        log = get_logger().bind(run_id="run_123")
+        log.info("Step started")
+    """
+    if name:
+        return logger.bind(module=name)
+    return logger
+
+
+def bind_workflow_context(run_id: str, workflow_name: str) -> Any:
+    """
+    Bind workflow context to logger.
+
+    This adds run_id and workflow_name to all subsequent log messages.
+
+    Args:
+        run_id: Workflow run identifier
+        workflow_name: Workflow name
+
+    Returns:
+        Logger with bound context
+
+    Example:
+        log = bind_workflow_context("run_123", "process_order")
+        log.info("Workflow started")
+        # Output includes run_id and workflow_name
+    """
+    return logger.bind(run_id=run_id, workflow_name=workflow_name)
+
+
+def bind_step_context(run_id: str, step_id: str, step_name: str) -> Any:
+    """
+    Bind step context to logger.
+
+    This adds run_id, step_id, and step_name to all subsequent log messages.
+
+    Args:
+        run_id: Workflow run identifier
+        step_id: Step identifier
+        step_name: Step name
+
+    Returns:
+        Logger with bound context
+
+    Example:
+        log = bind_step_context("run_123", "step_abc", "validate_order")
+        log.info("Step executing")
+        # Output includes run_id, step_id, and step_name
+    """
+    return logger.bind(run_id=run_id, step_id=step_id, step_name=step_name)
+
+
+# Default configuration on import
+# Users can override by calling configure_logging()
+try:
+    # Only configure if logger doesn't have handlers
+    if len(logger._core.handlers) == 0:  # type: ignore[attr-defined]
+        configure_logging(level="INFO", show_context=False)
+except Exception:
+    # If configuration fails, just use default loguru
+    pass

pyworkflow/primitives/__init__.py

@@ -0,0 +1,33 @@
+"""
+Workflow primitives for durable execution.
+
+Primitives provide building blocks for workflow orchestration:
+- sleep: Durable delays without holding resources
+- hook: Wait for external events (webhooks, approvals, callbacks)
+- define_hook: Create typed hooks with Pydantic validation
+- resume_hook: Resume suspended workflows from external systems
+- shield: Protection from cancellation for critical sections
+- continue_as_new: Continue workflow with fresh event history
+"""
+
+from pyworkflow.primitives.continue_as_new import continue_as_new
+from pyworkflow.primitives.define_hook import TypedHook, define_hook
+from pyworkflow.primitives.hooks import hook
+from pyworkflow.primitives.resume_hook import ResumeResult, resume_hook
+from pyworkflow.primitives.shield import shield
+from pyworkflow.primitives.sleep import sleep
+
+__all__ = [
+    # Sleep
+    "sleep",
+    # Hooks
+    "hook",
+    "define_hook",
+    "TypedHook",
+    "resume_hook",
+    "ResumeResult",
+    # Cancellation
+    "shield",
+    # Continue-as-new
+    "continue_as_new",
+]