diff --git a/README.md b/README.md index e0048a088a..461f790942 100644 --- a/README.md +++ b/README.md @@ -1625,7 +1625,7 @@ To get started quickly using Nexus with Temporal, see the Python Nexus sample: https://github.com/temporalio/samples-python/tree/nexus/hello_nexus. -Two types of Nexus operation are supported, each using a decorator: +Nexus operation handlers can use one of these decorators: - `@temporalio.nexus.workflow_run_operation`: a Nexus operation that is backed by a Temporal workflow. The operation handler you write will start the handler workflow and then respond with a token indicating that the handler workflow @@ -1633,6 +1633,15 @@ Two types of Nexus operation are supported, each using a decorator: failure) to the caller workflow. - `@nexusrpc.handler.sync_operation`: an operation that responds synchronously. It may be `def` or `async def` and it may do network I/O, but it must respond within 10 seconds. +- `@temporalio.nexus.temporal_operation`: an experimental decorator for an `async def` that receives a + `TemporalNexusClient` and the operation input. Return `TemporalOperationResult.sync(value)` for a synchronous + Nexus response. To start a Workflow, Workflow Update, or Activity that completes the Nexus operation later, + return the `TemporalOperationResult` from the corresponding client method. + +In a Temporal operation handler, `nexus.info()` provides the service, operation, endpoint, worker namespace and task +queue, and the opaque start request ID when available. `nexus.info().cancellation_token` observes cancellation of the +current handler invocation, such as a request timeout. Worker Nexus inbound interceptors can read incoming headers from +`input.ctx.headers`. The following steps are an overview of the [Python Nexus sample]( https://github.com/temporalio/samples-python/tree/nexus/hello_nexus). @@ -1655,6 +1664,7 @@ https://github.com/temporalio/samples-python/tree/nexus/hello_nexus). class MyNexusService: my_sync_operation: nexusrpc.Operation[MyInput, MyOutput] my_workflow_run_operation: nexusrpc.Operation[MyInput, MyOutput] + my_temporal_operation: nexusrpc.Operation[MyInput, MyOutput] ``` 3. Implement your operation handlers in a service handler: @@ -1676,6 +1686,14 @@ https://github.com/temporalio/samples-python/tree/nexus/hello_nexus). input, id=str(uuid.uuid4()), ) + + @nexus.temporal_operation + async def my_temporal_operation( + self, client: nexus.TemporalNexusClient, input: MyInput + ) -> nexus.TemporalOperationResult[MyOutput]: + return nexus.TemporalOperationResult.sync( + MyOutput(message=f"Hello {input.name} from {nexus.info().operation}!") + ) ``` 4. Register your service handler with a Temporal worker. diff --git a/changelog/changed/curious-nexus-tern.md b/changelog/changed/curious-nexus-tern.md new file mode 100644 index 0000000000..d548884f5f --- /dev/null +++ b/changelog/changed/curious-nexus-tern.md @@ -0,0 +1 @@ +Experimental Temporal Nexus start handlers now accept `(client, input)` and typed cancel overrides accept only their options. Use `temporalio.nexus.info()` for invocation metadata and a read-only cancellation token. diff --git a/temporalio/client/_nexus.py b/temporalio/client/_nexus.py index fa22c11c24..ac449cbc5f 100644 --- a/temporalio/client/_nexus.py +++ b/temporalio/client/_nexus.py @@ -664,7 +664,6 @@ async def start_operation( operation: Callable[ [ NexusServiceType, - temporalio.nexus.TemporalStartOperationContext, temporalio.nexus.TemporalNexusClient, InputT, ], @@ -941,7 +940,6 @@ async def execute_operation( operation: Callable[ [ NexusServiceType, - temporalio.nexus.TemporalStartOperationContext, temporalio.nexus.TemporalNexusClient, InputT, ], diff --git a/temporalio/nexus/__init__.py b/temporalio/nexus/__init__.py index bb7fea18a5..fbf5c809a8 100644 --- a/temporalio/nexus/__init__.py +++ b/temporalio/nexus/__init__.py @@ -16,8 +16,7 @@ Info, LoggerAdapter, NexusCallback, - TemporalCancelOperationContext, - TemporalStartOperationContext, + OperationCancellationToken, WorkflowRunOperationContext, client, in_operation, @@ -46,9 +45,8 @@ "Info", "LoggerAdapter", "NexusCallback", + "OperationCancellationToken", "WorkflowRunOperationContext", - "TemporalCancelOperationContext", - "TemporalStartOperationContext", "client", "create_completion_callback", "in_operation", diff --git a/temporalio/nexus/_decorators.py b/temporalio/nexus/_decorators.py index 2dd2b35544..3baa64bdf3 100644 --- a/temporalio/nexus/_decorators.py +++ b/temporalio/nexus/_decorators.py @@ -20,10 +20,7 @@ ) from temporalio.types import NexusServiceType -from ._operation_context import ( - TemporalStartOperationContext, - WorkflowRunOperationContext, -) +from ._operation_context import WorkflowRunOperationContext from ._operation_handlers import ( TemporalOperationHandler, WorkflowRunOperationHandler, @@ -148,7 +145,6 @@ async def _start( TemporalOperationStartHandlerFunc: TypeAlias = Callable[ [ NexusServiceType, - TemporalStartOperationContext, TemporalNexusClient, InputT, ], @@ -184,7 +180,9 @@ def temporal_operation( TemporalOperationStartHandlerFunc[NexusServiceType, InputT, OutputT], ] ): - """Decorator marking a method as the start method for an operation that interacts with Temporal. + """Decorate an async ``(self, client, input)`` Nexus start method. + + Return a :py:class:`TemporalOperationResult` and use :py:func:`info` for invocation information. .. warning:: This API is experimental and unstable. @@ -204,29 +202,16 @@ def decorator( ) = get_temporal_operation_start_method_input_and_output_type_annotations(start) def operation_handler_factory( - self: NexusServiceType, + instance: NexusServiceType, ) -> OperationHandler[InputT, OutputT]: - async def _start( - ctx: TemporalStartOperationContext, - client: TemporalNexusClient, - input: InputT, - ) -> TemporalOperationResult[OutputT]: - return await start( - self, - ctx, - client, - input, - ) - class _TemporalOperationHandler(TemporalOperationHandler): @override async def start_operation( self, - ctx: TemporalStartOperationContext, client: TemporalNexusClient, input: InputT, ) -> TemporalOperationResult[OutputT]: - return await _start(ctx, client, input) + return await start(instance, client, input) _TemporalOperationHandler.start_operation.__doc__ = start.__doc__ return _TemporalOperationHandler() diff --git a/temporalio/nexus/_notification.py b/temporalio/nexus/_notification.py index 31d954d8d2..35d4e68487 100644 --- a/temporalio/nexus/_notification.py +++ b/temporalio/nexus/_notification.py @@ -13,10 +13,7 @@ import temporalio.converter from . import notifications -from ._operation_context import ( - TemporalStartOperationContext, - WorkflowRunOperationContext, -) +from ._operation_context import WorkflowRunOperationContext from ._temporal_client import TemporalNexusClient, TemporalOperationResult from ._token import WorkflowHandle from ._util import get_operation_factory @@ -257,7 +254,6 @@ def create_completion_callback( operation: Callable[ [ Any, - TemporalStartOperationContext, TemporalNexusClient, notifications.OnCompleteRequest[ temporalio.common.RawValue, HandlerSourceContextT @@ -276,7 +272,6 @@ def create_completion_callback( operation: Callable[ [ Any, - TemporalStartOperationContext, TemporalNexusClient, notifications.OnCompleteRequest[HandlerOutputT, HandlerSourceContextT], ], diff --git a/temporalio/nexus/_operation_context.py b/temporalio/nexus/_operation_context.py index 92c74ac308..3e3a67e8be 100644 --- a/temporalio/nexus/_operation_context.py +++ b/temporalio/nexus/_operation_context.py @@ -27,9 +27,9 @@ from nexusrpc.handler import ( CancelOperationContext, OperationContext, + OperationTaskCancellation, StartOperationContext, ) -from typing_extensions import Self import temporalio.api.common.v1 import temporalio.api.nexus.v1 @@ -114,6 +114,38 @@ def reserve(self) -> Generator[None]: ) +class OperationCancellationToken: + """Observe cancellation of the current Nexus handler invocation. + + A request to cancel the Nexus operation itself is delivered separately to the + handler's cancel method. Get this token from :py:attr:`Info.cancellation_token`. + """ + + def __init__(self, task_cancellation: OperationTaskCancellation) -> None: + """Initialize the token. Obtain one from the operation info.""" + self.__task_cancellation = task_cancellation + + def is_cancelled(self) -> bool: + """Return whether cancellation of the handler invocation was requested.""" + return self.__task_cancellation.is_cancelled() + + def cancellation_reason(self) -> str | None: + """Return the reason for cancellation, if available.""" + return self.__task_cancellation.cancellation_reason() + + async def wait_until_cancelled(self) -> None: + """Wait for cancellation of this invocation. + + Async handlers can receive :py:class:`asyncio.CancelledError` at an await. + The worker records the cancellation reason before interrupting the handler. + """ + await self.__task_cancellation.wait_until_cancelled() + + def wait_until_cancelled_sync(self, timeout: float | None = None) -> bool: + """Return whether cancellation occurred within the given timeout in seconds.""" + return self.__task_cancellation.wait_until_cancelled_sync(timeout) + + @dataclass(frozen=True) class Info: """Information about the running Nexus operation. @@ -130,6 +162,44 @@ class Info: task_queue: str """The task queue of the worker handling this Nexus operation.""" + service: str + """The service name for the current Nexus request.""" + + operation: str + """The operation name for the current Nexus request.""" + + request_id: str | None + """Opaque ID shared by retries of the same start request, if available. + + Cancel invocations have no start request ID. + """ + + cancellation_token: OperationCancellationToken + """Read-only token for observing cancellation of this handler invocation.""" + + @classmethod + def _from_operation_context( + cls, + context: OperationContext, + *, + endpoint: str, + namespace: str, + task_queue: str, + ) -> Info: + return cls( + endpoint=endpoint, + namespace=namespace, + task_queue=task_queue, + service=context.service, + operation=context.operation, + request_id=( + (context.request_id or None) + if isinstance(context, StartOperationContext) + else None + ), + cancellation_token=OperationCancellationToken(context.task_cancellation), + ) + def in_operation() -> bool: """Whether the current code is inside a Nexus operation.""" @@ -138,7 +208,7 @@ def in_operation() -> bool: def info() -> Info: """Get the current Nexus operation information.""" - return _temporal_context().info() + return _temporal_context().info def client() -> temporalio.client.Client: @@ -226,7 +296,7 @@ def _current_propagated_nexus_serialization_context() -> ( # pyright: ignore[re if nexus_ctx is None: return None return temporalio.api.nexus.v1.PropagatedSerializationContext( - endpoint=nexus_ctx.info().endpoint, + endpoint=nexus_ctx.info.endpoint, service=nexus_ctx.nexus_context.service, operation=nexus_ctx.nexus_context.operation, ) @@ -253,7 +323,7 @@ class _TemporalOperationCtx(Generic[_OperationCtxT]): client: temporalio.client.Client """The Temporal client in use by the worker handling the current Nexus operation.""" - info: Callable[[], Info] + info: Info """Temporal information about the running Nexus operation.""" nexus_context: _OperationCtxT @@ -270,7 +340,7 @@ def metric_meter(self) -> temporalio.common.MetricMeter: { "nexus_service": self.nexus_context.service, "nexus_operation": self.nexus_context.operation, - "task_queue": self.info().task_queue, + "task_queue": self.info.task_queue, } ) return self._metric_meter @@ -642,34 +712,6 @@ def set(self) -> None: _temporal_cancel_operation_context.set(self) -class TemporalStartOperationContext(StartOperationContext): - """Context received by a Temporal Nexus operation when it is started. - - .. warning:: - This API is experimental and unstable. - """ - - @classmethod - def _from_start_operation_context(cls, ctx: StartOperationContext) -> Self: - return cls( - **{f.name: getattr(ctx, f.name) for f in dataclasses.fields(ctx)}, - ) - - -class TemporalCancelOperationContext(CancelOperationContext): - """Context received by a Temporal Nexus operation when it is canceled. - - .. warning:: - This API is experimental and unstable. - """ - - @classmethod - def _from_cancel_operation_context(cls, ctx: CancelOperationContext) -> Self: - return cls( - **{f.name: getattr(ctx, f.name) for f in dataclasses.fields(ctx)}, - ) - - class LoggerAdapter(logging.LoggerAdapter): """Logger adapter that adds Nexus operation context information.""" @@ -685,7 +727,7 @@ def process( if tctx := _try_temporal_context(): extra["service"] = tctx.nexus_context.service extra["operation"] = tctx.nexus_context.operation - extra["task_queue"] = tctx.info().task_queue + extra["task_queue"] = tctx.info.task_queue kwargs["extra"] = extra | kwargs.get("extra", {}) return msg, kwargs @@ -737,7 +779,7 @@ async def _start_nexus_backing_workflow( arg=arg, args=args, id=id, - task_queue=task_queue or temporal_context.info().task_queue, + task_queue=task_queue or temporal_context.info.task_queue, result_type=result_type, execution_timeout=execution_timeout, run_timeout=run_timeout, diff --git a/temporalio/nexus/_operation_handlers.py b/temporalio/nexus/_operation_handlers.py index b51507f71f..b41ad4bf0c 100644 --- a/temporalio/nexus/_operation_handlers.py +++ b/temporalio/nexus/_operation_handlers.py @@ -21,8 +21,6 @@ import temporalio.nexus from temporalio.nexus._operation_context import ( - TemporalCancelOperationContext, - TemporalStartOperationContext, _SignalSlot, _temporal_cancel_operation_context, ) @@ -183,11 +181,10 @@ class TemporalOperationHandler(OperationHandler[InputT, OutputT], ABC): @abstractmethod async def start_operation( self, - ctx: TemporalStartOperationContext, client: TemporalNexusClient, input: InputT, ) -> TemporalOperationResult[OutputT]: - """Start the Temporal-backed Nexus operation.""" + """Start the operation. Use :py:func:`temporalio.nexus.info` for invocation information.""" ... async def start( @@ -199,9 +196,8 @@ async def start( This API is experimental and unstable. """ nexus_client = _TemporalNexusClient() - start_ctx = TemporalStartOperationContext._from_start_operation_context(ctx) with _SignalSlot.scope(): - result = await self.start_operation(start_ctx, nexus_client, input) + result = await self.start_operation(nexus_client, input) return result._to_nexus_result() async def cancel(self, ctx: CancelOperationContext, token: str) -> None: @@ -219,14 +215,13 @@ async def cancel(self, ctx: CancelOperationContext, token: str) -> None: retryable_override=False, ) from err - cancel_ctx = TemporalCancelOperationContext._from_cancel_operation_context(ctx) match operation_token.type: case OperationTokenType.WORKFLOW: assert operation_token.workflow_id is not None options = CancelWorkflowRunOptions( workflow_id=operation_token.workflow_id ) - await self.cancel_workflow_run(cancel_ctx, options) + await self.cancel_workflow_run(options) case OperationTokenType.UPDATE_WORKFLOW: assert operation_token.workflow_id is not None assert operation_token.update_id is not None @@ -236,7 +231,7 @@ async def cancel(self, ctx: CancelOperationContext, token: str) -> None: update_id=operation_token.update_id, run_id=operation_token.run_id, ) - await self.cancel_workflow_update(cancel_ctx, cancel_options) + await self.cancel_workflow_update(cancel_options) case OperationTokenType.ACTIVITY: assert operation_token.activity_id is not None if not operation_token.run_id: @@ -247,7 +242,6 @@ async def cancel(self, ctx: CancelOperationContext, token: str) -> None: ) await self.cancel_activity( - cancel_ctx, CancelActivityOptions( activity_id=operation_token.activity_id, run_id=operation_token.run_id, @@ -256,7 +250,6 @@ async def cancel(self, ctx: CancelOperationContext, token: str) -> None: async def cancel_workflow_run( self, - ctx: TemporalCancelOperationContext, # pyright: ignore[reportUnusedParameter] options: CancelWorkflowRunOptions, ) -> None: """Cancels the workflow backing the Nexus operation. @@ -271,7 +264,6 @@ async def cancel_workflow_run( async def cancel_workflow_update( self, - ctx: TemporalCancelOperationContext, # pyright: ignore[reportUnusedParameter] options: CancelUpdateWorkflowOptions, # pyright: ignore[reportUnusedParameter] ) -> None: """Cancels the Workflow Update triggered by the Nexus operation. There is no native way to cancel an accepted Update, so cancellation depends on the Update handler itself. @@ -291,7 +283,6 @@ async def cancel_workflow_update( async def cancel_activity( self, - ctx: TemporalCancelOperationContext, # pyright: ignore[reportUnusedParameter] options: CancelActivityOptions, ) -> None: """Requests cancellation of the standalone activity backing the operation.""" diff --git a/temporalio/nexus/_temporal_client.py b/temporalio/nexus/_temporal_client.py index 4fd34d9394..403e3042d8 100644 --- a/temporalio/nexus/_temporal_client.py +++ b/temporalio/nexus/_temporal_client.py @@ -775,7 +775,7 @@ async def start_activity( arg=arg, args=args, id=id, - task_queue=task_queue or self._temporal_context.info().task_queue, + task_queue=task_queue or self._temporal_context.info.task_queue, result_type=result_type, schedule_to_start_timeout=schedule_to_start_timeout, schedule_to_close_timeout=schedule_to_close_timeout, diff --git a/temporalio/nexus/_util.py b/temporalio/nexus/_util.py index f129dda2bd..cb7dbe24af 100644 --- a/temporalio/nexus/_util.py +++ b/temporalio/nexus/_util.py @@ -15,10 +15,7 @@ OutputT, ) -from temporalio.nexus._operation_context import ( - TemporalStartOperationContext, - WorkflowRunOperationContext, -) +from temporalio.nexus._operation_context import WorkflowRunOperationContext from temporalio.nexus._temporal_client import ( TemporalNexusClient, TemporalOperationResult, @@ -55,7 +52,6 @@ def get_temporal_operation_start_method_input_and_output_type_annotations( start: Callable[ [ NexusServiceType, - TemporalStartOperationContext, TemporalNexusClient, InputT, ], @@ -70,12 +66,15 @@ def get_temporal_operation_start_method_input_and_output_type_annotations( ``start`` must be a type-annotated start method that returns a :py:class:`temporalio.nexus.TemporalOperationResult`. """ + try: + inspect.signature(start).bind(None, None, None) + except TypeError as err: + raise TypeError( + f"@temporal_operation method {start} must accept (self, client, input)." + ) from err return _get_wrapped_start_method_input_and_output_type_annotations( start, - expected_param_types=( - TemporalStartOperationContext, - TemporalNexusClient, - ), + expected_param_types=(TemporalNexusClient,), expected_return_origin=TemporalOperationResult, ) diff --git a/temporalio/worker/_nexus.py b/temporalio/worker/_nexus.py index e53efba5ab..dfe1506203 100644 --- a/temporalio/worker/_nexus.py +++ b/temporalio/worker/_nexus.py @@ -296,7 +296,8 @@ async def _handle_cancel_operation_task( endpoint, request.service, request.operation ) temporalio.nexus._operation_context._TemporalCancelOperationContext( - info=lambda: Info( + info=Info._from_operation_context( + ctx, endpoint=endpoint, namespace=self._namespace, task_queue=self._task_queue, @@ -470,7 +471,8 @@ async def _start_operation( temporalio.nexus._operation_context._TemporalStartOperationContext( nexus_context=ctx, client=self._client, - info=lambda: Info( + info=Info._from_operation_context( + ctx, endpoint=endpoint, namespace=self._namespace, task_queue=self._task_queue, diff --git a/temporalio/workflow/_nexus.py b/temporalio/workflow/_nexus.py index a23432545a..c58e90e1b3 100644 --- a/temporalio/workflow/_nexus.py +++ b/temporalio/workflow/_nexus.py @@ -225,7 +225,6 @@ async def start_operation( operation: Callable[ [ NexusServiceType, - temporalio.nexus.TemporalStartOperationContext, temporalio.nexus.TemporalNexusClient, InputT, ], @@ -412,7 +411,6 @@ async def execute_operation( operation: Callable[ [ NexusServiceType, - temporalio.nexus.TemporalStartOperationContext, temporalio.nexus.TemporalNexusClient, InputT, ], diff --git a/tests/nexus/test_handler_operation_definitions.py b/tests/nexus/test_handler_operation_definitions.py index ef1e51ff61..7a3e0e91dd 100644 --- a/tests/nexus/test_handler_operation_definitions.py +++ b/tests/nexus/test_handler_operation_definitions.py @@ -5,7 +5,7 @@ import warnings from dataclasses import dataclass -from typing import Any, ClassVar +from typing import Any, ClassVar, cast import nexusrpc.handler import pytest @@ -102,20 +102,15 @@ async def test_collected_operation_names( assert actual_op.output_type == expected_op.output_type -def test_unsafe_narrow_context_annotations_warn_and_drop_input_type(): - """Unsafe context annotations warn and prevent input type inference. - - Decorators construct a specific context type at runtime. If a handler annotates a - narrower or unrelated context type, the decorator cannot safely call it, so we - should warn and avoid using the handler annotation to infer operation input type. - """ +def test_unsafe_narrow_parameter_annotations_warn_and_drop_input_type(): + """Narrower SDK parameter annotations prevent inference of the input type.""" with pytest.warns( UserWarning, - match="Expected parameter 1 .* TemporalStartOperationContext", + match="Expected parameter 1 .* TemporalNexusClient", ): - class MyTemporalOpCtx(nexus.TemporalStartOperationContext): + class MyTemporalNexusClient(nexus.TemporalNexusClient): def custom_method(self): raise NotImplementedError @@ -123,8 +118,7 @@ class TemporalOperationHandler: @nexus.temporal_operation # type: ignore[arg-type] async def op( self, - _ctx: MyTemporalOpCtx, - _client: nexus.TemporalNexusClient, + _client: MyTemporalNexusClient, _input: Input, ) -> nexus.TemporalOperationResult[Output]: raise NotImplementedError @@ -158,13 +152,8 @@ async def op( assert workflow_op.output_type == Output -def test_safe_broader_context_annotations_preserve_input_type_without_warnings(): - """Safe context annotations preserve input type inference without warnings. - - A handler can safely annotate a context parameter with the exact runtime context - type or a broader base type. These cases should keep handler-derived operation - input metadata intact. - """ +def test_safe_broader_parameter_annotations_preserve_input_type_without_warnings(): + """Broader SDK parameter annotations preserve inference of the input type.""" with warnings.catch_warnings(record=True) as caught: warnings.simplefilter("always") @@ -173,8 +162,7 @@ class TemporalOperationHandler: @nexus.temporal_operation async def op( self, - _ctx: nexusrpc.handler.StartOperationContext, - _client: nexus.TemporalNexusClient, + _client: object, _input: Input, ) -> nexus.TemporalOperationResult[Output]: raise NotImplementedError @@ -198,3 +186,16 @@ async def op( assert isinstance(op, nexusrpc.Operation) assert op.input_type == Input assert op.output_type == Output + + +def test_temporal_operation_rejects_old_context_parameter(): + async def start( + _self: object, + _ctx: nexusrpc.handler.StartOperationContext, + _client: nexus.TemporalNexusClient, + _input: None, + ) -> None: + pass + + with pytest.raises(TypeError, match=r"must accept \(self, client, input\)"): + nexus.temporal_operation(cast(Any, start)) diff --git a/tests/nexus/test_link_propagation.py b/tests/nexus/test_link_propagation.py index f656f57c10..a89eddc60e 100644 --- a/tests/nexus/test_link_propagation.py +++ b/tests/nexus/test_link_propagation.py @@ -113,8 +113,8 @@ def nexus_ctx() -> Generator[_TemporalStartOperationContext]: ctx = temporalio.nexus._operation_context._TemporalStartOperationContext( nexus_context=nexus_context, client=mock.MagicMock(namespace=NAMESPACE), - info=lambda: temporalio.nexus.Info( - endpoint="endpoint", namespace=NAMESPACE, task_queue="tq" + info=temporalio.nexus.Info._from_operation_context( + nexus_context, endpoint="endpoint", namespace=NAMESPACE, task_queue="tq" ), _runtime_metric_meter=mock.MagicMock(), _worker_shutdown_event=mock.MagicMock(), @@ -146,8 +146,8 @@ def nexus_ctx_linkless() -> Generator[_TemporalStartOperationContext]: ctx = temporalio.nexus._operation_context._TemporalStartOperationContext( nexus_context=nexus_context, client=mock.MagicMock(namespace=NAMESPACE), - info=lambda: temporalio.nexus.Info( - endpoint="endpoint", namespace=NAMESPACE, task_queue="tq" + info=temporalio.nexus.Info._from_operation_context( + nexus_context, endpoint="endpoint", namespace=NAMESPACE, task_queue="tq" ), _runtime_metric_meter=mock.MagicMock(), _worker_shutdown_event=mock.MagicMock(), diff --git a/tests/nexus/test_nexus_handler_callbacks.py b/tests/nexus/test_nexus_handler_callbacks.py index a021f65d74..eb318babe1 100644 --- a/tests/nexus/test_nexus_handler_callbacks.py +++ b/tests/nexus/test_nexus_handler_callbacks.py @@ -170,7 +170,6 @@ async def workflow_run_on_complete( @nexus.temporal_operation(name="TemporalOnComplete") async def temporal_on_complete( self, - _ctx: nexus.TemporalStartOperationContext, _client: nexus.TemporalNexusClient, _input: notifications.OnCompleteRequest[NotificationValue, NotificationValue], ) -> nexus.TemporalOperationResult[notifications.OnCompleteResponse]: @@ -558,7 +557,6 @@ async def record_completion( @nexus.temporal_operation async def on_complete( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: notifications.OnCompleteRequest[EchoOutput, CallbackContext], ) -> nexus.TemporalOperationResult[notifications.OnCompleteResponse]: @@ -591,7 +589,6 @@ def __init__(self) -> None: @nexus.temporal_operation async def on_complete( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: notifications.OnCompleteRequest[EchoOutput, CallbackContext], ) -> nexus.TemporalOperationResult[notifications.OnCompleteResponse]: diff --git a/tests/nexus/test_nexus_type_errors.py b/tests/nexus/test_nexus_type_errors.py index 727299d1fe..39956548c0 100644 --- a/tests/nexus/test_nexus_type_errors.py +++ b/tests/nexus/test_nexus_type_errors.py @@ -111,7 +111,6 @@ async def workflow_run_on_raw_complete( @temporalio.nexus.temporal_operation async def temporal_on_complete( self, - _ctx: temporalio.nexus.TemporalStartOperationContext, _client: temporalio.nexus.TemporalNexusClient, _input: temporalio.nexus.notifications.OnCompleteRequest[ MyOutput, NotificationSourceContext @@ -124,7 +123,6 @@ async def temporal_on_complete( @temporalio.nexus.temporal_operation async def temporal_on_raw_complete( self, - _ctx: temporalio.nexus.TemporalStartOperationContext, _client: temporalio.nexus.TemporalNexusClient, _input: temporalio.nexus.notifications.OnCompleteRequest[ temporalio.common.RawValue, NotificationSourceContext @@ -461,7 +459,6 @@ async def my_workflow_run_operation( @temporalio.nexus.temporal_operation async def my_temporal_operation( self, - _ctx: temporalio.nexus.TemporalStartOperationContext, client: temporalio.nexus.TemporalNexusClient, input: int, ) -> temporalio.nexus.TemporalOperationResult[None]: @@ -683,7 +680,6 @@ async def my_workflow_run_operation( @temporalio.nexus.temporal_operation async def my_temporal_operation( self, - _ctx: temporalio.nexus.TemporalStartOperationContext, _client: temporalio.nexus.TemporalNexusClient, _input: int, ) -> temporalio.nexus.TemporalOperationResult[None]: @@ -707,7 +703,6 @@ async def my_workflow_run_operation( @temporalio.nexus.temporal_operation async def my_temporal_operation( self, - _ctx: temporalio.nexus.TemporalStartOperationContext, _client: temporalio.nexus.TemporalNexusClient, _input: int, ) -> temporalio.nexus.TemporalOperationResult[None]: @@ -734,21 +729,18 @@ async def my_temporal_operation( ] = MyServiceHandler.my_temporal_operation # type: ignore -class MyUnsafeContextAnnotationServiceHandler: - # A temporal operation receives TemporalStartOperationContext at runtime, so - # requiring an arbitrary user subclass is not safe. - class MyCustomTemporalStartOperationContext( - temporalio.nexus.TemporalStartOperationContext - ): +class MyUnsafeParameterAnnotationServiceHandler: + # A temporal operation receives TemporalNexusClient at runtime, so requiring + # an arbitrary user subclass is not safe. + class MyCustomTemporalNexusClient(temporalio.nexus.TemporalNexusClient): def custom_state(self) -> str: raise NotImplementedError # assert-type-error-pyright: 'cannot be assigned to parameter "start".+temporal_operation' @temporalio.nexus.temporal_operation # type: ignore - async def my_temporal_operation_with_workflow_run_context( + async def my_temporal_operation_with_custom_client( self, - _ctx: MyCustomTemporalStartOperationContext, - _client: temporalio.nexus.TemporalNexusClient, + _client: MyCustomTemporalNexusClient, _input: int, ) -> temporalio.nexus.TemporalOperationResult[None]: raise NotImplementedError diff --git a/tests/nexus/test_temporal_operation.py b/tests/nexus/test_temporal_operation.py index 030db6f6c9..307d7eb30f 100644 --- a/tests/nexus/test_temporal_operation.py +++ b/tests/nexus/test_temporal_operation.py @@ -42,6 +42,7 @@ from temporalio.nexus._token import OperationToken, OperationTokenType from temporalio.testing import WorkflowEnvironment from temporalio.worker import Worker +from temporalio.worker._nexus import _NexusTaskCancellation from tests.helpers import EventType, assert_event_subsequence, assert_eventually from tests.helpers.nexus import ( assert_links_match, @@ -85,6 +86,24 @@ def test_temporal_operation_result_validates_token() -> None: nexus.TemporalOperationResult(token=123) # type: ignore +@pytest.mark.parametrize( + ("request_id", "expected"), [("opaque/id-1", "opaque/id-1"), ("", None)] +) +def test_info_projects_start_request_id(request_id: str, expected: str | None): + ctx = StartOperationContext( + service="service", + operation="operation", + headers={"traceparent": "trace"}, + request_id=request_id, + task_cancellation=_NexusTaskCancellation(), + ) + info = nexus.Info._from_operation_context( + ctx, endpoint="endpoint", namespace="namespace", task_queue="queue" + ) + assert info.request_id == expected + assert ctx.request_id == request_id + + @workflow.defn class EchoWorkflow: @workflow.run @@ -147,16 +166,17 @@ class TestServiceHandler: def __init__(self) -> None: self.started_custom_cancel_workflow = asyncio.Event() + self.custom_workflow_start_infos: list[nexus.Info] = [] + self.custom_workflow_cancel_infos: list[nexus.Info] = [] self.started_custom_cancel_activity = asyncio.Event() self.custom_cancel_activity_called = asyncio.Event() self.bad_update_stage_error: ValueError | None = None - self.signal_handler_retry_request_ids: list[str] = [] + self.signal_handler_retry_request_ids: list[str | None] = [] self.concurrent_signal_results: list[BaseException | None] = [] @nexus.temporal_operation async def echo( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: @@ -167,7 +187,6 @@ async def echo( @nexus.temporal_operation async def blocking( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, _input: None, ) -> nexus.TemporalOperationResult[None]: @@ -178,7 +197,6 @@ async def blocking( @nexus.temporal_operation async def double_start( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[None]: @@ -193,7 +211,6 @@ async def double_start( @nexus.temporal_operation async def concurrent_start( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: @@ -238,7 +255,6 @@ async def concurrent_start( @nexus.temporal_operation async def retry_after_failed_start( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: @@ -260,7 +276,6 @@ async def retry_after_failed_start( @nexus.temporal_operation async def sync_result( self, - _ctx: nexus.TemporalStartOperationContext, _client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: @@ -268,30 +283,29 @@ async def sync_result( @operation_handler def custom_cancel(self) -> nexus.TemporalOperationHandler[str, None]: - event = self.started_custom_cancel_workflow + service_handler = self class CustomCancelNexusOpHandler(nexus.TemporalOperationHandler[str, None]): @override async def start_operation( self, - ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: str, ) -> nexus.TemporalOperationResult[None]: + info = nexus.info() result = await client.start_workflow(BlockingWorkflow.run, id=input) - event.set() + assert nexus.info() is info + service_handler.custom_workflow_start_infos.append(info) + service_handler.started_custom_cancel_workflow.set() return result @override async def cancel_workflow_run( self, - ctx: nexus.TemporalCancelOperationContext, options: nexus.CancelWorkflowRunOptions, ): - # get a handle to the workflow + service_handler.custom_workflow_cancel_infos.append(nexus.info()) handle = nexus.client().get_workflow_handle(options.workflow_id) - - # cancel the workflow await handle.cancel() return CustomCancelNexusOpHandler() @@ -299,7 +313,6 @@ async def cancel_workflow_run( @nexus.temporal_operation async def update_op( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: @@ -315,7 +328,6 @@ async def update_op( @nexus.temporal_operation async def bad_update_stage_op( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: @@ -335,7 +347,6 @@ async def bad_update_stage_op( @nexus.temporal_operation async def query_op( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: str, ) -> nexus.TemporalOperationResult[bool]: @@ -346,7 +357,6 @@ async def query_op( @nexus.temporal_operation async def echo_activity( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: @@ -360,7 +370,6 @@ async def echo_activity( @nexus.temporal_operation async def error_activity( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, _input: Input, ) -> nexus.TemporalOperationResult[None]: @@ -376,7 +385,6 @@ async def error_activity( @nexus.temporal_operation async def blocking_activity( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: str, ) -> nexus.TemporalOperationResult[None]: @@ -390,7 +398,6 @@ async def blocking_activity( @nexus.temporal_operation async def double_start_activity( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, _input: Input, ) -> nexus.TemporalOperationResult[None]: @@ -413,7 +420,6 @@ async def double_start_activity( @nexus.temporal_operation async def mixed_start( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[None]: @@ -433,7 +439,6 @@ async def mixed_start( @nexus.temporal_operation async def double_signal( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: str, ) -> nexus.TemporalOperationResult[None]: @@ -452,7 +457,6 @@ async def double_signal( @nexus.temporal_operation async def concurrent_signal( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: str, ) -> nexus.TemporalOperationResult[None]: @@ -475,7 +479,6 @@ async def unlimited_signals(self, _ctx: StartOperationContext, input: str) -> No @nexus.temporal_operation async def signal_after_failed_signal( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: str, ) -> nexus.TemporalOperationResult[None]: @@ -490,7 +493,6 @@ async def signal_after_failed_signal( @nexus.temporal_operation async def signal_handler_retry( self, - ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: str, ) -> nexus.TemporalOperationResult[None]: @@ -500,7 +502,7 @@ async def signal_handler_retry( task_queue=nexus.info().task_queue, start_signal="my_signal", ) - self.signal_handler_retry_request_ids.append(ctx.request_id) + self.signal_handler_retry_request_ids.append(nexus.info().request_id) if len(self.signal_handler_retry_request_ids) == 1: raise nexusrpc.HandlerError( "force handler redelivery after signaling", @@ -520,7 +522,6 @@ class CustomCancelActivityNexusOpHandler( @override async def start_operation( self, - ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: str, ) -> nexus.TemporalOperationResult[None]: @@ -536,7 +537,6 @@ async def start_operation( @override async def cancel_activity( self, - ctx: nexus.TemporalCancelOperationContext, options: nexus.CancelActivityOptions, ): # record that the custom override ran @@ -1155,6 +1155,16 @@ async def check_cancelled(): await assert_eventually(check_cancelled) + [start_info] = service_handler.custom_workflow_start_infos + [cancel_info] = service_handler.custom_workflow_cancel_infos + assert start_info.service == cancel_info.service == "TestService" + assert start_info.operation == cancel_info.operation == "custom_cancel" + assert start_info.request_id + assert cancel_info.request_id is None + assert start_info.cancellation_token is not cancel_info.cancellation_token + assert not hasattr(start_info, "headers") + assert not hasattr(cancel_info, "headers") + @workflow.defn class DoubleStartWorkflowCaller: @@ -1496,7 +1506,8 @@ async def test_temporal_operation_signal_deduped_across_handler_retry( task_queue = str(uuid.uuid4()) endpoint_name = make_nexus_endpoint_name(task_queue) await env.create_nexus_endpoint(endpoint_name, task_queue) - target_id = f"signal-retry-{uuid.uuid4()}" + retry_target = f"signal-retry-{uuid.uuid4()}" + independent_target = f"signal-independent-{uuid.uuid4()}" handler = TestServiceHandler() async with Worker( env.client, @@ -1505,17 +1516,17 @@ async def test_temporal_operation_signal_deduped_across_handler_retry( workflows=[SignalCountWorkflow], ): nexus_client = client.create_nexus_client(TestService, endpoint_name) - await nexus_client.execute_operation( - TestService.signal_handler_retry, target_id, id=str(uuid.uuid4()) - ) + for target_id in (retry_target, independent_target): + await nexus_client.execute_operation( + TestService.signal_handler_retry, target_id, id=str(uuid.uuid4()) + ) + handle = client.get_workflow_handle(target_id) + await handle.signal(SignalCountWorkflow.finish) + assert await handle.result() == 1 - request_ids = handler.signal_handler_retry_request_ids - assert len(request_ids) == 2 - assert request_ids[0] and request_ids[0] == request_ids[1] - - handle = client.get_workflow_handle(target_id) - await handle.signal(SignalCountWorkflow.finish) - assert await handle.result() == 1 + first, retry, independent = handler.signal_handler_retry_request_ids + assert first and retry == first + assert independent and independent != first @workflow.defn @@ -1557,6 +1568,60 @@ async def test_temporal_operation_sync_result(client: Client, env: WorkflowEnvir ) +async def test_temporal_operation_observes_invocation_timeout( + client: Client, env: WorkflowEnvironment +) -> None: + if env.supports_time_skipping_v1: + pytest.skip("Standalone Nexus Operation tests don't work with time skipping") + + observed: asyncio.Future[nexus.OperationCancellationToken] = ( + asyncio.get_running_loop().create_future() + ) + + @service_handler + class TimeoutService: + @nexus.temporal_operation + async def wait_for_cancellation( + self, _client: nexus.TemporalNexusClient, _input: None + ) -> nexus.TemporalOperationResult[None]: + token = nexus.info().cancellation_token + assert not token.is_cancelled() + assert token.cancellation_reason() is None + assert not token.wait_until_cancelled_sync(timeout=0) + + waiter = asyncio.create_task(token.wait_until_cancelled()) + try: + await asyncio.shield(waiter) + except asyncio.CancelledError: + assert nexus.info().cancellation_token is token + assert token.is_cancelled() + assert token.wait_until_cancelled_sync(timeout=0) + await asyncio.wait_for(waiter, timeout=1) + await asyncio.wait_for(token.wait_until_cancelled(), timeout=1) + observed.set_result(token) + raise + return nexus.TemporalOperationResult.sync(None) + + task_queue = str(uuid.uuid4()) + endpoint_name = make_nexus_endpoint_name(task_queue) + await env.create_nexus_endpoint(endpoint_name, task_queue) + async with Worker( + client, task_queue=task_queue, nexus_service_handlers=[TimeoutService()] + ): + nexus_client = client.create_nexus_client(TimeoutService, endpoint_name) + with pytest.raises(NexusOperationFailureError) as exc_info: + await nexus_client.execute_operation( + TimeoutService.wait_for_cancellation, + None, + id=str(uuid.uuid4()), + schedule_to_close_timeout=timedelta(seconds=3), + ) + assert isinstance(exc_info.value.__cause__, temporalio.exceptions.TimeoutError) + token: nexus.OperationCancellationToken = await asyncio.wait_for(observed, 5) + assert token.cancellation_reason() == "TIMED_OUT" + assert not hasattr(token, "cancel") + + async def test_temporal_operation_start_activity( client: Client, env: WorkflowEnvironment ): @@ -1602,7 +1667,6 @@ class LinkActivityHandler: @nexus.temporal_operation async def echo_activity( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: @@ -1816,7 +1880,6 @@ class TemporalOperationOverloadTestServiceHandler: @nexus.temporal_operation async def no_param( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, _input: TemporalOperationOverloadTestValue, ) -> nexus.TemporalOperationResult[TemporalOperationOverloadTestValue]: @@ -1828,7 +1891,6 @@ async def no_param( @nexus.temporal_operation async def single_param( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: TemporalOperationOverloadTestValue, ) -> nexus.TemporalOperationResult[TemporalOperationOverloadTestValue]: @@ -1841,7 +1903,6 @@ async def single_param( @nexus.temporal_operation async def multi_param( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: TemporalOperationOverloadTestValue, ) -> nexus.TemporalOperationResult[TemporalOperationOverloadTestValue]: @@ -1854,7 +1915,6 @@ async def multi_param( @nexus.temporal_operation async def by_name( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: TemporalOperationOverloadTestValue, ) -> nexus.TemporalOperationResult[TemporalOperationOverloadTestValue]: @@ -1868,7 +1928,6 @@ async def by_name( @nexus.temporal_operation async def by_name_multi_param( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: TemporalOperationOverloadTestValue, ) -> nexus.TemporalOperationResult[TemporalOperationOverloadTestValue]: @@ -2066,7 +2125,6 @@ class ActivityTokenHandler: @nexus.temporal_operation async def echo_activity( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: Input, ) -> nexus.TemporalOperationResult[str]: diff --git a/tests/nexus/test_workflow_caller_eviction.py b/tests/nexus/test_workflow_caller_eviction.py index c3081306a8..29be473258 100644 --- a/tests/nexus/test_workflow_caller_eviction.py +++ b/tests/nexus/test_workflow_caller_eviction.py @@ -45,7 +45,6 @@ class EvictionTestServiceHandler: @nexus.temporal_operation async def wait( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, workflow_id: str, ) -> nexus.TemporalOperationResult[str]: diff --git a/tests/test_serialization_context.py b/tests/test_serialization_context.py index fb7db6e6e7..b113d2d9d0 100644 --- a/tests/test_serialization_context.py +++ b/tests/test_serialization_context.py @@ -2734,7 +2734,6 @@ class NexusStartedExecutionHandler: @nexus.temporal_operation async def update_workflow( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: NexusUpdateInput, ) -> nexus.TemporalOperationResult[str]: @@ -2749,7 +2748,6 @@ async def update_workflow( @nexus.temporal_operation async def start_workflow( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: NexusStartedInput, ) -> nexus.TemporalOperationResult[str]: @@ -2758,7 +2756,6 @@ async def start_workflow( @nexus.temporal_operation async def start_retried_workflow( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: NexusStartedInput, ) -> nexus.TemporalOperationResult[str]: @@ -2774,7 +2771,6 @@ async def start_retried_workflow( @nexus.temporal_operation async def start_activity( self, - _ctx: nexus.TemporalStartOperationContext, client: nexus.TemporalNexusClient, input: NexusStartedInput, ) -> nexus.TemporalOperationResult[str]: