pyworkflow-engine 0.1.7__py3-none-any.whl

examples/local/durable/06_idempotency.py

@@ -0,0 +1,148 @@
+"""
+Durable Workflow - Idempotency
+
+This example demonstrates idempotency key usage to prevent duplicate workflow execution.
+- Same workflow called twice with same idempotency_key
+- Second call returns same run_id without re-execution
+- Prevents duplicate orders, payments, etc.
+- Uses FileStorageBackend for persistence
+
+Run: python examples/local/durable/06_idempotency.py 2>/dev/null
+"""
+
+import asyncio
+import tempfile
+
+from pyworkflow import (
+    configure,
+    get_workflow_run,
+    reset_config,
+    start,
+    step,
+    workflow,
+)
+from pyworkflow.storage import FileStorageBackend
+
+# Execution counter to track step calls
+execution_count = 0
+
+
+# --- Steps ---
+@step()
+async def create_order(order_id: str, amount: float) -> dict:
+    """Create a new order."""
+    global execution_count
+    execution_count += 1
+
+    print(f"  Creating order {order_id} for ${amount:.2f}...")
+    print(f"  (Execution count: {execution_count})")
+
+    return {"order_id": order_id, "amount": amount, "status": "created"}
+
+
+@step()
+async def charge_customer(order: dict) -> dict:
+    """Charge the customer."""
+    print(f"  Charging customer ${order['amount']:.2f}...")
+    return {**order, "charged": True}
+
+
+@step()
+async def send_confirmation(order: dict) -> dict:
+    """Send order confirmation."""
+    print(f"  Sending confirmation for order {order['order_id']}...")
+    return {**order, "confirmed": True}
+
+
+# --- Workflow ---
+@workflow(durable=True, tags=["local", "durable"])
+async def order_workflow(order_id: str, amount: float) -> dict:
+    """Complete order workflow (must be idempotent)."""
+    order = await create_order(order_id, amount)
+    order = await charge_customer(order)
+    order = await send_confirmation(order)
+    return order
+
+
+async def main():
+    global execution_count
+
+    # Use temp directory (use real path for production)
+    with tempfile.TemporaryDirectory() as tmpdir:
+        print("=== Durable Workflow - Idempotency ===\n")
+
+        # Configure with FileStorageBackend (for persistence)
+        reset_config()
+        storage = FileStorageBackend(base_path=tmpdir)
+        configure(storage=storage, default_durable=True)
+
+        # Reset execution count
+        execution_count = 0
+
+        # First call with idempotency key
+        print("First call: Creating order with idempotency_key='order-unique-123'...\n")
+        run_id_1 = await start(
+            order_workflow, "order-unique-123", 99.99, idempotency_key="order-unique-123"
+        )
+
+        run_1 = await get_workflow_run(run_id_1)
+        print("\nFirst call completed:")
+        print(f"  Run ID: {run_id_1}")
+        print(f"  Status: {run_1.status.value}")
+        print(f"  Result: {run_1.result}")
+        print(f"  Execution count: {execution_count}")
+
+        # Second call with SAME idempotency key
+        print("\n" + "=" * 60)
+        print("\nSecond call: Same idempotency_key='order-unique-123'...\n")
+        run_id_2 = await start(
+            order_workflow, "order-unique-123", 99.99, idempotency_key="order-unique-123"
+        )
+
+        run_2 = await get_workflow_run(run_id_2)
+        print("\nSecond call result:")
+        print(f"  Run ID: {run_id_2}")
+        print(f"  Status: {run_2.status.value}")
+        print(f"  Result: {run_2.result}")
+        print(f"  Execution count: {execution_count} (not incremented!)")
+
+        # Verify they're the same
+        print("\n" + "=" * 60)
+        print("\n=== Verification ===")
+        print(f"run_id_1 == run_id_2: {run_id_1 == run_id_2}")
+        print(f"Workflow re-executed: {execution_count > 1}")
+
+        if run_id_1 == run_id_2:
+            print("\n✓ SUCCESS: Same run_id returned, workflow NOT re-executed!")
+        else:
+            print("\n✗ UNEXPECTED: Different run_id, workflow was re-executed!")
+
+        # Third call with DIFFERENT idempotency key
+        print("\n" + "=" * 60)
+        print("\nThird call: Different idempotency_key='order-unique-456'...\n")
+        run_id_3 = await start(
+            order_workflow, "order-unique-456", 149.99, idempotency_key="order-unique-456"
+        )
+
+        run_3 = await get_workflow_run(run_id_3)
+        print("\nThird call result:")
+        print(f"  Run ID: {run_id_3}")
+        print(f"  Status: {run_3.status.value}")
+        print(f"  Execution count: {execution_count} (incremented!)")
+
+        print("\n=== Use Cases ===")
+        print("✓ Prevent duplicate orders from retry logic")
+        print("✓ Ensure exactly-once payment processing")
+        print("✓ Handle duplicate webhook deliveries")
+        print("✓ Guarantee idempotent API endpoints")
+
+        print("\n=== Key Takeaways ===")
+        print("✓ Same idempotency_key returns same run_id")
+        print("✓ Workflow NOT re-executed on duplicate key")
+        print("✓ Different keys create new workflow executions")
+        print("✓ Critical for financial transactions and critical workflows")
+        print("✓ Works across process restarts (persisted to storage)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/local/durable/07_hooks.py

@@ -0,0 +1,334 @@
+"""
+Durable Workflow - Hooks Example
+
+This example demonstrates the hooks feature for waiting on external events:
+- Using hook() to suspend workflow and wait for external input
+- Using define_hook() for typed hooks with Pydantic validation
+- Using resume_hook() to deliver payloads from external systems
+- Composite tokens (run_id:hook_id) for self-describing tokens
+- on_created callback for receiving the generated token
+
+Run: python examples/local/durable/07_hooks.py 2>/dev/null
+"""
+
+import asyncio
+
+from pydantic import BaseModel
+
+from pyworkflow import (
+    configure,
+    define_hook,
+    get_workflow_events,
+    get_workflow_run,
+    hook,
+    reset_config,
+    resume,
+    resume_hook,
+    start,
+    step,
+    workflow,
+)
+from pyworkflow.storage import InMemoryStorageBackend
+
+# Global storage reference for resumption
+_storage = None
+
+# Store tokens received from on_created callback
+_captured_tokens = {}
+
+
+# --- Pydantic models for typed hooks ---
+class ApprovalPayload(BaseModel):
+    """Typed payload for approval hook."""
+
+    approved: bool
+    reviewer: str
+    comments: str | None = None
+
+
+# Create typed hook
+approval_hook = define_hook("approval", ApprovalPayload)
+
+
+# --- Steps ---
+@step()
+async def prepare_order(order_id: str) -> dict:
+    """Prepare the order for review."""
+    print(f"  Preparing order {order_id}...")
+    return {"order_id": order_id, "status": "pending_approval"}
+
+
+@step()
+async def fulfill_order(order: dict) -> dict:
+    """Fulfill the approved order."""
+    print(f"  Fulfilling order {order['order_id']}...")
+    return {**order, "status": "fulfilled"}
+
+
+@step()
+async def cancel_order(order: dict, reason: str) -> dict:
+    """Cancel the rejected order."""
+    print(f"  Cancelling order {order['order_id']}: {reason}")
+    return {**order, "status": "cancelled", "reason": reason}
+
+
+# --- Workflow with simple hook ---
+@workflow(durable=True, name="simple_hook_workflow", tags=["local", "durable"])
+async def simple_hook_workflow(order_id: str) -> dict:
+    """
+    Workflow using simple hook() with untyped payload.
+
+    Demonstrates basic hook usage with auto-generated composite token.
+    Token format: run_id:hook_id (e.g., "run_abc123:hook_simple_approval_1")
+    """
+    order = await prepare_order(order_id)
+
+    async def capture_token(token: str):
+        """Capture the generated token for later use."""
+        _captured_tokens[order_id] = token
+        print(f"  Hook created with token: {token}")
+
+    # Wait for external approval using simple hook
+    # Token is auto-generated in composite format: run_id:hook_id
+    approval = await hook(
+        "simple_approval",
+        timeout="24h",  # Expire after 24 hours
+        on_created=capture_token,
+    )
+
+    if approval.get("approved"):
+        return await fulfill_order(order)
+    else:
+        return await cancel_order(order, approval.get("reason", "Rejected"))
+
+
+# --- Workflow with typed hook ---
+@workflow(durable=True, name="typed_hook_workflow", tags=["local", "durable"])
+async def typed_hook_workflow(order_id: str) -> dict:
+    """
+    Workflow using define_hook() for type-safe payloads.
+
+    Demonstrates typed hooks with Pydantic validation.
+    """
+    order = await prepare_order(order_id)
+
+    async def capture_typed_token(token: str):
+        """Capture the generated token for later use."""
+        _captured_tokens[f"typed:{order_id}"] = token
+        print(f"  Typed hook created with token: {token}")
+
+    # Wait for typed approval - payload is validated against ApprovalPayload
+    approval: ApprovalPayload = await approval_hook(
+        on_created=capture_typed_token,
+    )
+
+    print(f"  Received: approved={approval.approved}, reviewer={approval.reviewer}")
+
+    if approval.approved:
+        return await fulfill_order(order)
+    else:
+        return await cancel_order(order, approval.comments or "No reason given")
+
+
+# --- Workflow with on_created callback ---
+@workflow(durable=True, name="callback_hook_workflow", tags=["local", "durable"])
+async def callback_hook_workflow(order_id: str) -> dict:
+    """
+    Workflow demonstrating on_created callback.
+
+    The callback is invoked when the hook is created,
+    allowing you to notify external systems with the token.
+    Token format is composite: run_id:hook_id
+    """
+    order = await prepare_order(order_id)
+
+    async def on_hook_created(token: str):
+        # In real scenarios, you would notify external systems here
+        # e.g., send email, update database, register webhook URL
+        _captured_tokens[f"callback:{order_id}"] = token
+        print(f"  Hook created! Token: {token}")
+        print(f"  External system can POST to: /webhook/{token}")
+
+    # Wait for approval with on_created callback
+    approval = await hook(
+        "callback_approval",
+        on_created=on_hook_created,
+    )
+
+    if approval.get("approved"):
+        return await fulfill_order(order)
+    else:
+        return await cancel_order(order, approval.get("reason", "Rejected"))
+
+
+async def demo_simple_hook():
+    """Demo simple hook workflow."""
+    print("\n" + "=" * 50)
+    print("Demo 1: Simple Hook with Composite Token")
+    print("=" * 50)
+
+    run_id = await start(simple_hook_workflow, "ORDER-001")
+    print(f"\nWorkflow started: {run_id}")
+
+    # Check status - should be suspended
+    run = await get_workflow_run(run_id)
+    print(f"Status: {run.status.value}")
+
+    # Get the token that was captured via on_created callback
+    token = _captured_tokens.get("ORDER-001")
+    print(f"\nCaptured token: {token}")
+
+    # Simulate external system calling resume_hook with the composite token
+    print("\n[External System] Sending approval...")
+    result = await resume_hook(
+        token=token,
+        payload={"approved": True, "approver": "manager@example.com"},
+        storage=_storage,
+    )
+    print(f"Resume result: {result.status}")
+
+    # In local mode without Celery, manually resume the workflow
+    await resume(run_id, storage=_storage)
+
+    # Check final status
+    run = await get_workflow_run(run_id)
+    print(f"\nFinal status: {run.status.value}")
+    print(f"Result: {run.result}")
+
+
+async def demo_typed_hook():
+    """Demo typed hook workflow."""
+    print("\n" + "=" * 50)
+    print("Demo 2: Typed Hook with Pydantic")
+    print("=" * 50)
+
+    run_id = await start(typed_hook_workflow, "ORDER-002")
+    print(f"\nWorkflow started: {run_id}")
+
+    # Check status - should be suspended
+    run = await get_workflow_run(run_id)
+    print(f"Status: {run.status.value}")
+
+    # Get the token that was captured via on_created callback
+    token = _captured_tokens.get("typed:ORDER-002")
+    print(f"\nCaptured token: {token}")
+
+    # Simulate external system calling resume_hook with typed payload
+    print("\n[External System] Sending typed approval...")
+    result = await resume_hook(
+        token=token,
+        payload={
+            "approved": True,
+            "reviewer": "jane.doe@example.com",
+            "comments": "Looks good!",
+        },
+        storage=_storage,
+    )
+    print(f"Resume result: {result.status}")
+
+    # In local mode without Celery, manually resume the workflow
+    await resume(run_id, storage=_storage)
+
+    # Check final status
+    run = await get_workflow_run(run_id)
+    print(f"\nFinal status: {run.status.value}")
+    print(f"Result: {run.result}")
+
+
+async def demo_rejection():
+    """Demo hook rejection flow."""
+    print("\n" + "=" * 50)
+    print("Demo 3: Rejection Flow")
+    print("=" * 50)
+
+    run_id = await start(simple_hook_workflow, "ORDER-003")
+    print(f"\nWorkflow started: {run_id}")
+
+    # Get the token that was captured via on_created callback
+    token = _captured_tokens.get("ORDER-003")
+
+    # Simulate rejection
+    print("\n[External System] Sending rejection...")
+    result = await resume_hook(
+        token=token,
+        payload={"approved": False, "reason": "Insufficient inventory"},
+        storage=_storage,
+    )
+    print(f"Resume result: {result.status}")
+
+    # In local mode without Celery, manually resume the workflow
+    await resume(run_id, storage=_storage)
+
+    # Check final status
+    run = await get_workflow_run(run_id)
+    print(f"\nFinal status: {run.status.value}")
+    print(f"Result: {run.result}")
+
+
+async def demo_event_log():
+    """Show the event log for a hook-based workflow."""
+    print("\n" + "=" * 50)
+    print("Demo 4: Event Log Inspection")
+    print("=" * 50)
+
+    run_id = await start(simple_hook_workflow, "ORDER-004")
+
+    # Get the token that was captured via on_created callback
+    token = _captured_tokens.get("ORDER-004")
+
+    # Resume hook using captured token
+    await resume_hook(
+        token=token,
+        payload={"approved": True},
+        storage=_storage,
+    )
+
+    # Resume workflow in local mode
+    await resume(run_id, storage=_storage)
+
+    # Inspect event log
+    events = await get_workflow_events(run_id)
+    print(f"\nEvent Log ({len(events)} events):")
+    for event in events:
+        print(f"  {event.sequence}: {event.type.value}")
+        if "hook" in event.type.value:
+            if "hook_id" in event.data:
+                print(f"     hook_id: {event.data.get('hook_id', 'N/A')}")
+            if "token" in event.data:
+                print(f"     token: {event.data.get('token', 'N/A')[:40]}...")
+
+
+async def main():
+    global _storage
+
+    # Configure with InMemoryStorageBackend
+    reset_config()
+    _storage = InMemoryStorageBackend()
+    configure(storage=_storage, default_durable=True)
+
+    print("=== Durable Workflow - Hooks Example ===")
+    print("""
+This example demonstrates hooks for external event integration:
+- hook(): Wait for external events
+- define_hook(): Create typed hooks with validation
+- resume_hook(): Deliver payloads from external systems
+""")
+
+    await demo_simple_hook()
+    await demo_typed_hook()
+    await demo_rejection()
+    await demo_event_log()
+
+    print("\n" + "=" * 50)
+    print("Key Takeaways")
+    print("=" * 50)
+    print("- hook() suspends workflow until resume_hook() is called")
+    print("- Tokens are auto-generated in composite format: run_id:hook_id")
+    print("- Use on_created callback to capture the token for external systems")
+    print("- define_hook() provides type-safe payloads with Pydantic")
+    print("- Composite tokens are self-describing (contain run_id)")
+    print("- Events record hook creation and reception")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())