Skip to content

TemporalOperationHandler context refactor - #3195

Merged
litlep-nibbyt merged 20 commits into
mainfrom
nexus-context-free-handler-prototype
Nov 19, 2026
Merged

litlep-nibbyt merged 20 commits into
mainfrom
nexus-context-free-handler-prototype

Conversation

@litlep-nibbyt

@litlep-nibbyt litlep-nibbyt commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

What was changed

Removed explicit context parameters from Temporal operation start and cancellation handlers:

  • Start handlers now accept (client, input).
  • Custom cancelWorkflowRun, cancelUpdateWorkflow, and cancelActivityExecution overrides accept only their typed input.
  • Deleted TemporalOperationStartContext and TemporalOperationCancelContext.
  • Added 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 returns null in 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

  1. 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.

  2. Any docs updates needed?
    Java API examples, Javadocs, and the changelog are updated. Samples and external documentation will follow separately.

  3. Server changes required?
    No.

@litlep-nibbyt
litlep-nibbyt force-pushed the nexus-context-free-handler-prototype branch from 11433f1 to 1cd2992 Compare November 10, 2026 22:28
temporalNexusContext.getTaskQueue(),
temporalNexusContext.getEndpoint())));
temporalNexusContext.getEndpoint(),
context.getService(),

@litlep-nibbyt litlep-nibbyt Nov 12, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we decided to keep this because types are exposed within workflow and activity.

@litlep-nibbyt
litlep-nibbyt marked this pull request as ready for review November 12, 2026 20:07
@litlep-nibbyt
litlep-nibbyt requested a review from a team as a code owner November 12, 2026 20:07

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

@litlep-nibbyt
litlep-nibbyt force-pushed the nexus-context-free-handler-prototype branch from b3424ef to f8b47df Compare November 17, 2026 00:05
}

@Override
public String getOperation() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about RequestID and Headers?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we decided to add requestId because its useful for request dedup

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

headers we will punt on since they are accessible through interceptors

@litlep-nibbyt
litlep-nibbyt force-pushed the nexus-context-free-handler-prototype branch from 0c7d727 to 7f6fe0d Compare November 18, 2026 21:02
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.
@litlep-nibbyt
litlep-nibbyt force-pushed the nexus-context-free-handler-prototype branch from 7f6fe0d to c03bf5f Compare November 18, 2026 22:11
Comment on lines +7 to +14
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() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is to be consistent with the Java SDK activity info Activity.getExecutionContext().getInfo();

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's fine, I added it for convenience

@litlep-nibbyt litlep-nibbyt Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
@litlep-nibbyt
litlep-nibbyt merged commit 050e9fd into main Nov 19, 2026
23 of 24 checks passed
@litlep-nibbyt
litlep-nibbyt deleted the nexus-context-free-handler-prototype branch November 19, 2026 00:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants