Nexus samples (#174)

Author: dandavison

hello_nexus/README.md

@@ -0,0 +1,37 @@
+This sample shows how to define a Nexus service, implement the operation handlers, and
+call the operations from a workflow.
+
+### Sample directory structure
+
+- [service.py](./service.py) - shared Nexus service definition
+- [caller](./caller) - a caller workflow that executes Nexus operations, together with a worker and starter code
+- [handler](./handler) - Nexus operation handlers, together with a workflow used by one of the Nexus operations, and a worker that polls for both workflow and Nexus tasks.
+
+
+### Instructions
+
+Start a Temporal server. (See the main samples repo [README](../README.md)).
+
+Run the following:
+
+```
+temporal operator namespace create --namespace hello-nexus-basic-handler-namespace
+temporal operator namespace create --namespace hello-nexus-basic-caller-namespace
+
+temporal operator nexus endpoint create \
+  --name hello-nexus-basic-nexus-endpoint \
+  --target-namespace hello-nexus-basic-handler-namespace \
+  --target-task-queue my-handler-task-queue \
+  --description-file hello_nexus/endpoint_description.md
+```
+
+In one terminal, run the Temporal worker in the handler namespace:
+```
+uv run hello_nexus/handler/worker.py
+```
+
+In another terminal, run the Temporal worker in the caller namespace and start the caller
+workflow:
+```
+uv run hello_nexus/caller/app.py
+```

hello_nexus/__init__.py

@@ -0,0 +1,43 @@
+import asyncio
+import uuid
+from typing import Optional
+
+from temporalio.client import Client
+from temporalio.worker import Worker
+
+from hello_nexus.caller.workflows import CallerWorkflow
+from hello_nexus.service import MyOutput
+
+NAMESPACE = "hello-nexus-basic-caller-namespace"
+TASK_QUEUE = "hello-nexus-basic-caller-task-queue"
+
+
+async def execute_caller_workflow(
+    client: Optional[Client] = None,
+) -> tuple[MyOutput, MyOutput]:
+    client = client or await Client.connect(
+        "localhost:7233",
+        namespace=NAMESPACE,
+    )
+
+    async with Worker(
+        client,
+        task_queue=TASK_QUEUE,
+        workflows=[CallerWorkflow],
+    ):
+        return await client.execute_workflow(
+            CallerWorkflow.run,
+            arg="world",
+            id=str(uuid.uuid4()),
+            task_queue=TASK_QUEUE,
+        )
+
+
+if __name__ == "__main__":
+    loop = asyncio.new_event_loop()
+    try:
+        results = loop.run_until_complete(execute_caller_workflow())
+        for output in results:
+            print(output.message)
+    except KeyboardInterrupt:
+        loop.run_until_complete(loop.shutdown_asyncgens())

hello_nexus/caller/__init__.py

@@ -0,0 +1,35 @@
+from temporalio import workflow
+
+with workflow.unsafe.imports_passed_through():
+    from hello_nexus.service import MyInput, MyNexusService, MyOutput
+
+NEXUS_ENDPOINT = "hello-nexus-basic-nexus-endpoint"
+
+
+# This is a workflow that calls two nexus operations.
+@workflow.defn
+class CallerWorkflow:
+    # An __init__ method is always optional on a workflow class. Here we use it to set the
+    # nexus client, but that could alternatively be done in the run method.
+    def __init__(self):
+        self.nexus_client = workflow.create_nexus_client(
+            service=MyNexusService,
+            endpoint=NEXUS_ENDPOINT,
+        )
+
+    # The workflow run method invokes two nexus operations.
+    @workflow.run
+    async def run(self, name: str) -> tuple[MyOutput, MyOutput]:
+        # Start the nexus operation and wait for the result in one go, using execute_operation.
+        wf_result = await self.nexus_client.execute_operation(
+            MyNexusService.my_workflow_run_operation,
+            MyInput(name),
+        )
+        # Alternatively, you can use start_operation to obtain the operation handle and
+        # then `await` the handle to obtain the result.
+        sync_operation_handle = await self.nexus_client.start_operation(
+            MyNexusService.my_sync_operation,
+            MyInput(name),
+        )
+        sync_result = await sync_operation_handle
+        return sync_result, wf_result

hello_nexus/caller/app.py

@@ -0,0 +1,3 @@
+## Service: [MyNexusService](https://github.com/temporalio/samples-python/blob/main/hello_nexus/basic/service.py)
+ - operation: `my_sync_operation`
+ - operation: `my_workflow_run_operation`

hello_nexus/caller/workflows.py

@@ -0,0 +1,49 @@
+"""
+This file demonstrates how to implement a Nexus service.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+import nexusrpc
+from temporalio import nexus
+
+from hello_nexus.handler.workflows import WorkflowStartedByNexusOperation
+from hello_nexus.service import MyInput, MyNexusService, MyOutput
+
+
+@nexusrpc.handler.service_handler(service=MyNexusService)
+class MyNexusServiceHandler:
+    # You can create an __init__ method accepting what is needed by your operation
+    # handlers to handle requests. You typically instantiate your service handler class
+    # when starting your worker. See hello_nexus/basic/handler/worker.py.
+
+    # This is a nexus operation that is backed by a Temporal workflow. The start method
+    # starts a workflow, and returns a nexus operation token. Meanwhile, the workflow
+    # executes in the background; Temporal server takes care of delivering the eventual
+    # workflow result (success or failure) to the calling workflow.
+    #
+    # The token will be used by the caller if it subsequently wants to cancel the Nexus
+    # operation.
+    @nexus.workflow_run_operation
+    async def my_workflow_run_operation(
+        self, ctx: nexus.WorkflowRunOperationContext, input: MyInput
+    ) -> nexus.WorkflowHandle[MyOutput]:
+        return await ctx.start_workflow(
+            WorkflowStartedByNexusOperation.run,
+            input,
+            id=str(uuid.uuid4()),
+        )
+
+    # This is a Nexus operation that responds synchronously to all requests. That means
+    # that unlike the workflow run operation above, in this case the `start` method
+    # returns the final operation result.
+    #
+    # Sync operations are free to make arbitrary network calls, or perform CPU-bound
+    # computations. Total execution duration must not exceed 10s.
+    @nexusrpc.handler.sync_operation
+    async def my_sync_operation(
+        self, ctx: nexusrpc.handler.StartOperationContext, input: MyInput
+    ) -> MyOutput:
+        return MyOutput(message=f"Hello {input.name} from sync operation!")

hello_nexus/endpoint_description.md

@@ -0,0 +1,46 @@
+import asyncio
+import logging
+from typing import Optional
+
+from temporalio.client import Client
+from temporalio.worker import Worker
+
+from hello_nexus.handler.service_handler import MyNexusServiceHandler
+from hello_nexus.handler.workflows import WorkflowStartedByNexusOperation
+
+interrupt_event = asyncio.Event()
+
+NAMESPACE = "hello-nexus-basic-handler-namespace"
+TASK_QUEUE = "my-handler-task-queue"
+
+
+async def main(client: Optional[Client] = None):
+    logging.basicConfig(level=logging.INFO)
+
+    client = client or await Client.connect(
+        "localhost:7233",
+        namespace=NAMESPACE,
+    )
+
+    # Start the worker, passing the Nexus service handler instance, in addition to the
+    # workflow classes that are started by your nexus operations, and any activities
+    # needed. This Worker will poll for both workflow tasks and Nexus tasks (this example
+    # doesn't use any activities).
+    async with Worker(
+        client,
+        task_queue=TASK_QUEUE,
+        workflows=[WorkflowStartedByNexusOperation],
+        nexus_service_handlers=[MyNexusServiceHandler()],
+    ):
+        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())

hello_nexus/handler/__init__.py

@@ -0,0 +1,12 @@
+from temporalio import workflow
+
+with workflow.unsafe.imports_passed_through():
+    from hello_nexus.service import MyInput, MyOutput
+
+
+# This is the workflow that is started by the `my_workflow_run_operation` nexus operation.
+@workflow.defn
+class WorkflowStartedByNexusOperation:
+    @workflow.run
+    async def run(self, input: MyInput) -> MyOutput:
+        return MyOutput(message=f"Hello {input.name} from workflow run operation!")