diff --git a/README.md b/README.md index f1256f301..80728c174 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,7 @@ Some examples require extra dependencies. See each sample's directory for specif * [litellm_activity](litellm_activity) - Call LLM providers through LiteLLM from a Temporal Activity. * [message_passing/introduction](message_passing/introduction/) - Introduction to queries, signals, and updates. * [message_passing/safe_message_handlers](message_passing/safe_message_handlers/) - Safely handling updates and signals. +* [message_passing/update_with_start/early_return](message_passing/update_with_start/early_return/) - Use update-with-start to return an authorization result before the Workflow finishes. * [message_passing/update_with_start/lazy_initialization](message_passing/update_with_start/lazy_initialization/) - Use update-with-start to update a Shopping Cart, starting it if it does not exist. * [nexus_cancel](nexus_cancel) - Fan out concurrent Nexus operations, take the first result, and cancel the rest. * [nexus_messaging](nexus_messaging): Demonstrates how to send signal, update and query messages through Nexus. diff --git a/message_passing/update_with_start/early_return/README.md b/message_passing/update_with_start/early_return/README.md new file mode 100644 index 000000000..b7b2a97fd --- /dev/null +++ b/message_passing/update_with_start/early_return/README.md @@ -0,0 +1,18 @@ +# Update With Start: Early return + +This sample uses Update-with-Start to start payment processing and return its +authorization result before the Workflow finishes. The client can move on after +authorization while Temporal continues the slower capture step. + +To run, first see the main [README.md](../../../README.md) for prerequisites. + +Then run the following from the root directory: + + uv run message_passing/update_with_start/early_return/worker.py + +In another terminal, run: + + uv run message_passing/update_with_start/early_return/starter.py + +The starter returns after authorization. The worker logs the capture later, when +the Workflow completes. diff --git a/message_passing/update_with_start/early_return/__init__.py b/message_passing/update_with_start/early_return/__init__.py new file mode 100644 index 000000000..11e1e0d6c --- /dev/null +++ b/message_passing/update_with_start/early_return/__init__.py @@ -0,0 +1 @@ +TASK_QUEUE = "update-with-start-early-return" diff --git a/message_passing/update_with_start/early_return/activities.py b/message_passing/update_with_start/early_return/activities.py new file mode 100644 index 000000000..67a0d6b50 --- /dev/null +++ b/message_passing/update_with_start/early_return/activities.py @@ -0,0 +1,33 @@ +import asyncio +import uuid +from dataclasses import dataclass + +from temporalio import activity + + +@dataclass(frozen=True) +class PaymentDetails: + amount: int + + +@dataclass(frozen=True) +class PaymentAuthorization: + id: str + amount: int + + +@activity.defn +async def authorize_payment(details: PaymentDetails) -> PaymentAuthorization: + await asyncio.sleep(0.5) + authorization = PaymentAuthorization( + id=f"authorization-{uuid.uuid4()}", + amount=details.amount, + ) + activity.logger.info("Payment authorized: %s", authorization.id) + return authorization + + +@activity.defn +async def capture_payment(authorization: PaymentAuthorization) -> None: + await asyncio.sleep(5) + activity.logger.info("Payment captured: %s", authorization.id) diff --git a/message_passing/update_with_start/early_return/starter.py b/message_passing/update_with_start/early_return/starter.py new file mode 100644 index 000000000..5d1319f06 --- /dev/null +++ b/message_passing/update_with_start/early_return/starter.py @@ -0,0 +1,40 @@ +import asyncio +import uuid + +from temporalio import common +from temporalio.client import Client, WithStartWorkflowOperation +from temporalio.envconfig import ClientConfig + +from message_passing.update_with_start.early_return import TASK_QUEUE +from message_passing.update_with_start.early_return.activities import PaymentDetails +from message_passing.update_with_start.early_return.workflows import PaymentWorkflow + + +async def main() -> None: + config = ClientConfig.load_client_connect_config() + config.setdefault("target_host", "localhost:7233") + client = await Client.connect(**config) + + payment_id = f"payment-{uuid.uuid4()}" + start_operation = WithStartWorkflowOperation( + PaymentWorkflow.run, + PaymentDetails(amount=500), + id=payment_id, + id_conflict_policy=common.WorkflowIDConflictPolicy.FAIL, + task_queue=TASK_QUEUE, + ) + + authorization = await client.execute_update_with_start_workflow( + PaymentWorkflow.wait_until_authorized, + start_workflow_operation=start_operation, + ) + workflow_handle = await start_operation.workflow_handle() + + print( + f"Payment {workflow_handle.id} was authorized as {authorization.id}. " + "Capture will continue in the Workflow." + ) + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/message_passing/update_with_start/early_return/worker.py b/message_passing/update_with_start/early_return/worker.py new file mode 100644 index 000000000..bf8c1e2fe --- /dev/null +++ b/message_passing/update_with_start/early_return/worker.py @@ -0,0 +1,42 @@ +import asyncio +import logging + +from temporalio.client import Client +from temporalio.envconfig import ClientConfig +from temporalio.worker import Worker + +from message_passing.update_with_start.early_return import TASK_QUEUE +from message_passing.update_with_start.early_return.activities import ( + authorize_payment, + capture_payment, +) +from message_passing.update_with_start.early_return.workflows import PaymentWorkflow + +interrupt_event = asyncio.Event() + + +async def main() -> None: + logging.basicConfig(level=logging.INFO) + + config = ClientConfig.load_client_connect_config() + config.setdefault("target_host", "localhost:7233") + client = await Client.connect(**config) + + async with Worker( + client, + task_queue=TASK_QUEUE, + workflows=[PaymentWorkflow], + activities=[authorize_payment, capture_payment], + ): + logging.info("Worker started, ctrl+c to exit") + await interrupt_event.wait() + logging.info("Shutting down") + + +if __name__ == "__main__": + loop = asyncio.new_event_loop() + try: + loop.run_until_complete(main()) + except KeyboardInterrupt: + interrupt_event.set() + loop.run_until_complete(loop.shutdown_asyncgens()) diff --git a/message_passing/update_with_start/early_return/workflows.py b/message_passing/update_with_start/early_return/workflows.py new file mode 100644 index 000000000..c4eda7775 --- /dev/null +++ b/message_passing/update_with_start/early_return/workflows.py @@ -0,0 +1,39 @@ +from datetime import timedelta +from typing import Optional + +from temporalio import workflow + +with workflow.unsafe.imports_passed_through(): + from message_passing.update_with_start.early_return.activities import ( + PaymentAuthorization, + PaymentDetails, + authorize_payment, + capture_payment, + ) + + +@workflow.defn +class PaymentWorkflow: + def __init__(self) -> None: + self.authorization: Optional[PaymentAuthorization] = None + + @workflow.run + async def run(self, details: PaymentDetails) -> PaymentAuthorization: + self.authorization = await workflow.execute_activity( + authorize_payment, + details, + start_to_close_timeout=timedelta(seconds=10), + ) + + await workflow.execute_activity( + capture_payment, + self.authorization, + start_to_close_timeout=timedelta(seconds=30), + ) + return self.authorization + + @workflow.update + async def wait_until_authorized(self) -> PaymentAuthorization: + await workflow.wait_condition(lambda: self.authorization is not None) + assert self.authorization is not None + return self.authorization diff --git a/tests/message_passing/early_return/test_early_return.py b/tests/message_passing/early_return/test_early_return.py new file mode 100644 index 000000000..e30e9c716 --- /dev/null +++ b/tests/message_passing/early_return/test_early_return.py @@ -0,0 +1,59 @@ +import asyncio +import uuid + +from temporalio import activity, common +from temporalio.client import Client, WithStartWorkflowOperation +from temporalio.worker import Worker + +from message_passing.update_with_start.early_return.activities import ( + PaymentAuthorization, + PaymentDetails, +) +from message_passing.update_with_start.early_return.workflows import PaymentWorkflow + + +async def test_update_result_arrives_before_workflow_completes(client: Client) -> None: + task_queue = f"early-return-{uuid.uuid4()}" + capture_started = asyncio.Event() + release_capture = asyncio.Event() + + @activity.defn(name="authorize_payment") + async def authorize_payment(details: PaymentDetails) -> PaymentAuthorization: + return PaymentAuthorization(id="test-authorization", amount=details.amount) + + @activity.defn(name="capture_payment") + async def capture_payment(authorization: PaymentAuthorization) -> None: + capture_started.set() + await release_capture.wait() + + async with Worker( + client, + task_queue=task_queue, + workflows=[PaymentWorkflow], + activities=[authorize_payment, capture_payment], + ): + start_operation = WithStartWorkflowOperation( + PaymentWorkflow.run, + PaymentDetails(amount=500), + id=f"early-return-{uuid.uuid4()}", + id_conflict_policy=common.WorkflowIDConflictPolicy.FAIL, + task_queue=task_queue, + ) + + authorization = await client.execute_update_with_start_workflow( + PaymentWorkflow.wait_until_authorized, + start_workflow_operation=start_operation, + ) + workflow_handle = await start_operation.workflow_handle() + workflow_result = asyncio.create_task(workflow_handle.result()) + + await capture_started.wait() + await asyncio.sleep(0) + + assert authorization == PaymentAuthorization( + id="test-authorization", amount=500 + ) + assert workflow_result.done() is False + + release_capture.set() + assert await workflow_result == authorization