Repository navigation
TemporalOperationHandler context refactor - #3195
Conversation
11433f1 to
1cd2992
Compare
| temporalNexusContext.getTaskQueue(), | ||
| temporalNexusContext.getEndpoint()))); | ||
| temporalNexusContext.getEndpoint(), | ||
| context.getService(), |
There was a problem hiding this comment.
service and operation weren't explicitly mentioned in the spec as something to keep in the NexusInfo. They are used in the tests to create a workflow ID. afaik, workflow ID is chosen in application code and we recommend that users set it to a meaningful business id., so we can probably remove it?
There was a problem hiding this comment.
we decided to keep this because types are exposed within workflow and activity.
There was a problem hiding this comment.
🟡 Changes recommended
NexusOperationInfo lacks a deadline accessor, preventing migrated start and cancellation handlers from inspecting their remaining time budget as they could with the removed context classes.
1 open issue
What changed in this PR
This PR simplifies Temporal’s Nexus handler API by removing explicit context parameters and exposing invocation information through Nexus.getInfo(). The underlying Nexus RPC handler contract remains unchanged.
Changes:
- Change start handlers to
(client, input)and cancellation overrides to typed input only. - Expose service, operation, and read-only invocation cancellation through
Nexus.getInfo(). - Update Java and Kotlin tests, API examples, and migration notes; add cancellation and interceptor coverage.
| File | Description |
|---|---|
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/UpdateWorkflowOperationTest.java | Adopt the context-free start signature. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/TemporalOperationAnnotationTest.java | Migrate annotated handlers and workflow IDs. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/NexusSerializationContextPropagationTest.java | Update handler signatures and information access. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/NexusOperationInfoTest.java | Access information through Nexus.getInfo(). |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerUntypedStartWorkflowTest.java | Migrate untyped workflow handlers. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerTypedStartWorkflowTest.java | Migrate typed workflow handlers. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerTypedProcTest.java | Migrate void-result workflow handlers. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerSyncResultTest.java | Migrate synchronous-result handlers. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerSignalDeduplicationTest.java | Track retry attempts without exposing request IDs. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerDoubleStartTest.java | Update double-start handlers and metadata access. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerCancelTest.java | Migrate workflow cancellation test handlers. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/CancelActivityAsyncOperationTest.java | Update activity start and cancellation signatures. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/AsyncActivityOperationTest.java | Update activity handlers and activity IDs. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/ActivityOperationLinkingTest.java | Use the new information accessor. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/ActivityHandleUseExistingOnConflictTest.java | Migrate conflict-reuse handlers. |
| temporal-sdk/src/test/java/io/temporal/workflow/nexus/ActivityHandleFailOnConflictTest.java | Migrate conflict-failure handlers. |
| temporal-sdk/src/test/java/io/temporal/nexus/TemporalOperationHandlerTest.java | Add typed cancellation-dispatch coverage. |
| temporal-sdk/src/test/java/io/temporal/internal/nexus/TemporalOperationProcessorTest.java | Update signature validation and invocation tests. |
| temporal-sdk/src/test/java/io/temporal/internal/nexus/TemporalInterceptorMiddlewareTest.java | Add header-access and cancellation-token coverage. |
| temporal-sdk/src/test/java/io/temporal/internal/nexus/NexusTaskHandlerImplTest.java | Verify timeout cancellation reaches context-free handlers. |
| temporal-sdk/src/test/java/io/temporal/client/nexus/StandaloneNexusSignalLinkingTest.java | Update task-queue information access. |
| temporal-sdk/src/test/java/io/temporal/client/nexus/NexusClientTest.java | Migrate the activity-backed handler. |
| temporal-sdk/src/main/java/io/temporal/nexus/TemporalOperationStartContext.java | Remove the explicit start context class. |
| temporal-sdk/src/main/java/io/temporal/nexus/TemporalOperationHandler.java | Simplify start and cancellation dispatch signatures. |
| temporal-sdk/src/main/java/io/temporal/nexus/TemporalOperationCancelContext.java | Remove the explicit cancellation context class. |
| temporal-sdk/src/main/java/io/temporal/nexus/TemporalOperation.java | Document the two-parameter annotation contract. |
| temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClient.java | Update documentation and handler examples. |
| temporal-sdk/src/main/java/io/temporal/nexus/NexusOperationInfo.java | Add service, operation, and cancellation accessors. |
| temporal-sdk/src/main/java/io/temporal/nexus/Nexus.java | Add the static getInfo() convenience method. |
| temporal-sdk/src/main/java/io/temporal/internal/nexus/TemporalOperationProcessor.java | Validate and invoke two-parameter handlers. |
| temporal-sdk/src/main/java/io/temporal/internal/nexus/TemporalInterceptorMiddleware.java | Bridge invocation cancellation into operation information. |
| temporal-sdk/src/main/java/io/temporal/internal/nexus/NexusInfoImpl.java | Store and expose the added invocation information. |
| temporal-kotlin/src/test/kotlin/io/temporal/workflow/KotlinTemporalOperationTest.kt | Migrate the Kotlin annotated handler. |
| CHANGELOG.md | Document the breaking API migration. |
Review effort: Balanced
b3424ef to
f8b47df
Compare
| } | ||
|
|
||
| @Override | ||
| public String getOperation() { |
There was a problem hiding this comment.
What about RequestID and Headers?
There was a problem hiding this comment.
I intentionally left both out of Nexus.getInfo() based on the design clarification. Interceptors can still read the request headers, and the start-operation interceptors can read the request ID from the start details.
Do you see a use case that needs either field directly in a handler?
There was a problem hiding this comment.
we decided to add requestId because its useful for request dedup
There was a problem hiding this comment.
headers we will punt on since they are accessible through interceptors
0c7d727 to
7f6fe0d
Compare
Give Temporal operation handlers the incoming request ID through Nexus.getInfo().getRequestId() so they can deduplicate side effects on retry. Return null for cancel handlers and starts without an ID. Test that start handlers receive the exact ID for each invocation, retries reuse it, and cancel handlers receive null. Restore Workflow and Activity test fixture IDs derived from the start request ID. Assert the captured header after the handler call so a skipped interceptor fails the test. Share setup for the tests that cancel before and after interception.
7f6fe0d to
c03bf5f
Compare
| public final class Nexus { | ||
| /** | ||
| * Get information about the current Nexus Operation. | ||
| * | ||
| * <p>This static method relies on a thread-local variable and works only in the original Nexus | ||
| * thread. | ||
| */ | ||
| public static NexusOperationInfo getInfo() { |
There was a problem hiding this comment.
Why did we add this? The way users get Info in the Java SDK is through Nexus.getOperationContext().getInfo() that is already exposed and we generally don't make two ways to do the same thing
There was a problem hiding this comment.
This is to be consistent with the Java SDK activity info Activity.getExecutionContext().getInfo();
There was a problem hiding this comment.
that's fine, I added it for convenience
There was a problem hiding this comment.
It was to shorten invocations like this:
WorkflowOptions.newBuilder()
.setWorkflowId("sugar-" + Nexus.getOperationContext().getInfo().getRequestId())
.build());
Use the existing Nexus operation context accessor for operation info. Update Javadocs, release notes, and tests to use that access path.

What was changed
Removed explicit context parameters from Temporal operation start and cancellation handlers:
(client, input).cancelWorkflowRun,cancelUpdateWorkflow, andcancelActivityExecutionoverrides accept only their typed input.TemporalOperationStartContextandTemporalOperationCancelContext.Nexus.getInfo()for operation information, including service, operation, a read-only handler-invocation cancellation token, and the start request ID.getRequestId()returns the same ID on retries of the same start request and returnsnullin cancel handlers.Request headers remain available to interceptors. Callbacks and links still propagate automatically, and SDK deduplication is preserved.
Breaking change: existing Temporal handlers must drop their context parameter. The underlying Nexus RPC handler contract is unchanged.
Why?
Simplify handler signatures and keep transport details out of application code while preserving access to operation information and invocation cancellation.
Checklist
How was this tested?
Local all-module and targeted dev-server tests passed during implementation. Added coverage for invocation cancellation, request-timeout propagation into a context-free handler, cancellation dispatch, and interceptor header access. Request ID tests verify that start handlers receive the exact incoming ID, retries reuse it, and cancel handlers see
null. Formatting and Javadocs passed.Any docs updates needed?
Java API examples, Javadocs, and the changelog are updated. Samples and external documentation will follow separately.
Server changes required?
No.