Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
233f825
start:
litlep-nibbyt Nov 6, 2026
7525d3e
chore: make tests great again
litlep-nibbyt Nov 6, 2026
7161e89
feat: add direct Nexus operation info accessor
litlep-nibbyt Nov 10, 2026
e819eb3
feat: expose Nexus request ID through operation info
litlep-nibbyt Nov 10, 2026
9fd257b
test: migrate Temporal operation handlers to context-free signature
litlep-nibbyt Nov 10, 2026
3eae86d
test: cover ambient Nexus cancellation and deadline
litlep-nibbyt Nov 10, 2026
1793ab1
fix: keep Nexus request ID internal
litlep-nibbyt Nov 10, 2026
981cf95
refactor: remove explicit context from Temporal cancellation handlers
litlep-nibbyt Nov 10, 2026
2334f01
test: verify interceptor header access with context-free handler
litlep-nibbyt Nov 10, 2026
3dba9a5
test: clarify interceptor header regression test name
litlep-nibbyt Nov 10, 2026
d193c96
test: migrate Kotlin Temporal operation to context-free signature
litlep-nibbyt Nov 11, 2026
922d10b
docs: update context-free Temporal handler examples and API comments
litlep-nibbyt Nov 11, 2026
13e0b6f
docs: add changelog entry for context-free Temporal handlers
litlep-nibbyt Nov 12, 2026
b78bec7
Remove deadline from Nexus operation info
litlep-nibbyt Nov 12, 2026
682d658
Remove obsolete start context and strengthen handler tests
litlep-nibbyt Nov 13, 2026
118f3c4
Test request timeout cancellation in a context-free handler
litlep-nibbyt Nov 14, 2026
bb10b28
Move context refactor changelog entry to Unreleased
litlep-nibbyt Nov 17, 2026
c03bf5f
Expose Nexus start request IDs through operation info
litlep-nibbyt Nov 18, 2026
acb17d0
Remove the Nexus operation info shortcut
litlep-nibbyt Nov 18, 2026
29102bb
Document Nexus cancellation callback threading
litlep-nibbyt Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,14 @@ to docs, or any other relevant information.
`upsertTypedSearchAttributes(UpsertSearchAttributesOptions, ...)`, and
`upsertMemo(Map, UpsertMemoOptions)` methods. Implementations that don't extend
`WorkflowOutboundCallsInterceptorBase` need to add them, and Base subclasses override them to see calls with options.
- **Experimental**: Temporal operation start handlers, including `@TemporalOperation` methods, now
accept only `(TemporalNexusClient, input)`. Cancellation overrides now accept only their typed
input. `TemporalOperationStartContext` and `TemporalOperationCancelContext` have been removed.
Use `Nexus.getOperationContext().getInfo()` for service, operation, a read-only handler
invocation cancellation token, and the start request ID (`getRequestId()`, which returns `null`
in cancel handlers).
Request headers remain available to interceptors. Callbacks and Nexus links are no longer exposed
to Temporal operation handlers.

### Added
- Experimental Event Groups associate related workflow commands so their history events can be
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ import io.temporal.common.converter.KotlinObjectMapperFactory
import io.temporal.nexus.TemporalNexusClient
import io.temporal.nexus.TemporalOperation
import io.temporal.nexus.TemporalOperationResult
import io.temporal.nexus.TemporalOperationStartContext
import io.temporal.testing.internal.SDKTestWorkflowRule
import org.junit.Assert.assertEquals
import org.junit.Rule
Expand Down Expand Up @@ -43,7 +42,6 @@ class KotlinTemporalOperationTest {
class KotlinSugarServiceImpl {
@TemporalOperation
fun greet(
ctx: TemporalOperationStartContext,
client: TemporalNexusClient,
input: String
): TemporalOperationResult<String> {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,16 +1,34 @@
package io.temporal.internal.nexus;

import io.temporal.common.CancellationToken;
import io.temporal.nexus.NexusOperationInfo;
import java.util.concurrent.CancellationException;
import javax.annotation.Nullable;

class NexusInfoImpl implements NexusOperationInfo {
private final String namespace;
private final String taskQueue;
private final String endpoint;
private final String service;
private final String operation;
private final @Nullable String requestId;
private final CancellationToken<CancellationException> cancellationToken;

NexusInfoImpl(String namespace, String taskQueue, String endpoint) {
NexusInfoImpl(
String namespace,
String taskQueue,
String endpoint,
String service,
String operation,
@Nullable String requestId,
CancellationToken<CancellationException> cancellationToken) {
this.namespace = namespace;
this.taskQueue = taskQueue;
this.endpoint = endpoint;
this.service = service;
this.operation = operation;
this.requestId = requestId;
this.cancellationToken = cancellationToken;
}

@Override
Expand All @@ -27,4 +45,24 @@ public String getTaskQueue() {
public String getEndpoint() {
return endpoint;
}

@Override
public String getService() {
return service;
}

@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

return operation;
}

@Override
public @Nullable String getRequestId() {
return requestId;
}

@Override
public CancellationToken<CancellationException> getCancellationToken() {
return cancellationToken;
}
}
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
package io.temporal.internal.nexus;

import com.google.common.base.Strings;
import io.nexusrpc.OperationException;
import io.nexusrpc.handler.*;
import io.temporal.common.interceptors.NexusOperationInboundCallsInterceptor;
import io.temporal.common.interceptors.WorkerInterceptor;
import io.temporal.internal.concurrent.structured.CancelSource;
import java.util.concurrent.CancellationException;

public class TemporalInterceptorMiddleware implements OperationMiddleware {
private final WorkerInterceptor[] interceptors;
Expand All @@ -24,14 +27,21 @@ public OperationHandler<Object, Object> intercept(
}

InternalNexusOperationContext temporalNexusContext = CurrentNexusOperationContext.get();
CancelSource<CancellationException> cancellationSource =
new CancelSource<>(() -> new CancellationException(context.getMethodCancellationReason()));
context.addMethodCancellationListener(cancellationSource::cancel);
inboundCallsInterceptor.init(
new RootNexusOperationOutboundCallsInterceptor(
temporalNexusContext.getMetricsScope(),
temporalNexusContext.getWorkflowClient(),
new NexusInfoImpl(
temporalNexusContext.getNamespace(),
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.

context.getOperation(),
Strings.emptyToNull(temporalNexusContext.getRequestId()),
cancellationSource.token())));
return new OperationInterceptorConverter(inboundCallsInterceptor);
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@
import io.temporal.nexus.TemporalOperation;
import io.temporal.nexus.TemporalOperationHandler;
import io.temporal.nexus.TemporalOperationResult;
import io.temporal.nexus.TemporalOperationStartContext;
import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodHandles;
import java.lang.reflect.Method;
Expand Down Expand Up @@ -62,7 +61,7 @@ private static final class TemporalOperationExtension implements MethodExtension
}

TemporalOperationHandler.StartHandler<Object, Object> startHandler =
(ctx, client, input) -> invokeStartHandler(handle, ctx, client, input);
(client, input) -> invokeStartHandler(handle, client, input);

return new TemporalOperationHandler<Object, Object>(startHandler) {};
}
Expand All @@ -78,13 +77,11 @@ private static void validateSignature(Method method) {
"@TemporalOperation method " + method.getName() + " must not be static");
}
Class<?>[] paramTypes = method.getParameterTypes();
if (paramTypes.length != 3
|| !TemporalOperationStartContext.class.equals(paramTypes[0])
|| !TemporalNexusClient.class.equals(paramTypes[1])) {
if (paramTypes.length != 2 || !TemporalNexusClient.class.equals(paramTypes[0])) {
throw new IllegalArgumentException(
"@TemporalOperation method "
+ method.getName()
+ " must accept (TemporalOperationStartContext, TemporalNexusClient, I); got "
+ " must accept (TemporalNexusClient, I); got "
+ describeSignature(method));
}
if (!TemporalOperationResult.class.equals(method.getReturnType())) {
Expand Down Expand Up @@ -112,7 +109,7 @@ private static void validateSignature(Method method) {

private static void validateTypes(Method method, OperationDefinition operationDefinition) {
Type expectedInputType = operationDefinition.getInputType();
Type declaredInputType = method.getGenericParameterTypes()[2];
Type declaredInputType = method.getGenericParameterTypes()[1];
if (!typesMatch(declaredInputType, expectedInputType)) {
throw new IllegalArgumentException(
"@TemporalOperation method "
Expand Down Expand Up @@ -144,13 +141,9 @@ private static void validateTypes(Method method, OperationDefinition operationDe
// Package-private for testing.
@SuppressWarnings("unchecked")
static TemporalOperationResult<Object> invokeStartHandler(
MethodHandle handle,
TemporalOperationStartContext ctx,
TemporalNexusClient client,
Object input)
throws OperationException {
MethodHandle handle, TemporalNexusClient client, Object input) throws OperationException {
try {
return (TemporalOperationResult<Object>) handle.invoke(ctx, client, input);
return (TemporalOperationResult<Object>) handle.invoke(client, input);
} catch (RuntimeException | Error | OperationException e) {
// HandlerException is a RuntimeException and falls into the RuntimeException arm.
throw e;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
package io.temporal.nexus;

import io.temporal.common.CancellationToken;
import java.util.concurrent.CancellationException;
import javax.annotation.Nullable;

/**
* Temporal information about the Nexus Operation. Use {@link NexusOperationContext#getInfo()} from
* a Nexus Operation implementation to access.
* Temporal information about the Nexus Operation. Use {@link NexusOperationContext#getInfo()
* Nexus.getOperationContext().getInfo()} from a Nexus Operation implementation to access.
*/
public interface NexusOperationInfo {
/**
Expand All @@ -20,4 +24,37 @@ public interface NexusOperationInfo {
* Supported from server v1.30.0.
*/
String getEndpoint();

/**
* @return Service name for the current Nexus request.
*/
String getService();

/**
* @return Operation name for the current Nexus request.
*/
String getOperation();

/**
* Returns the ID of the current Nexus start request, or {@code null} when no ID is available (for
* example, in a cancel handler).
*
* <p>Retries of the same start request carry the same ID. Treat the ID as an opaque string.
*/
@Nullable
default String getRequestId() {
return null;
}

/**
* Returns a read-only token for observing cancellation of the current handler invocation. This is
* separate from a request to cancel the Nexus Operation itself.
*
* <p>When cancellation is requested, {@link CancellationToken#throwIfCancellationRequested()}
* throws a {@link CancellationException} whose message contains the invocation cancellation
* reason.
*
* <p>Cancellation callbacks may run on the Nexus timeout thread and must return promptly.
*/
CancellationToken<CancellationException> getCancellationToken();
Comment thread
litlep-nibbyt marked this conversation as resolved.
Resolved
}
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,16 @@
* Temporal from within a Nexus operation handler.
*
* <p>Passed to {@link TemporalOperation}-annotated methods (and {@link
* TemporalOperationHandler.StartHandler} implementations) alongside the start context and input.
* TemporalOperationHandler.StartHandler} implementations) alongside the operation input. Access
* information about the current invocation through {@link NexusOperationContext#getInfo()
* Nexus.getOperationContext().getInfo()}.
*
* <p>Example usage to start a workflow from an operation:
*
* <pre>{@code
* @TemporalOperation
* public TemporalOperationResult<TransferResult> startTransfer(
* TemporalOperationStartContext ctx, TemporalNexusClient client, TransferInput input) {
* TemporalNexusClient client, TransferInput input) {
* return client.startWorkflow(
* TransferWorkflow.class,
* TransferWorkflow::transfer,
Expand All @@ -39,7 +41,7 @@
* <pre>{@code
* @TemporalOperation
* public TemporalOperationResult<Void> cancelOrder(
* TemporalOperationStartContext ctx, TemporalNexusClient client, CancelOrderInput input) {
* TemporalNexusClient client, CancelOrderInput input) {
* client.getWorkflowClient()
* .newUntypedWorkflowStub("order-" + input.getOrderId())
* .signal("requestCancellation", input);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,7 @@
*
* <ul>
* <li>be {@code public},
* <li>accept exactly three parameters: {@link TemporalOperationStartContext}, {@link
* TemporalNexusClient}, and the operation input type,
* <li>accept exactly two parameters: {@link TemporalNexusClient} and the operation input type,
* <li>return {@link TemporalOperationResult}.
* </ul>
*
Expand All @@ -30,7 +29,7 @@
* public class TransferServiceImpl {
* @TemporalOperation
* public TemporalOperationResult<TransferResult> transfer(
* TemporalOperationStartContext ctx, TemporalNexusClient client, TransferInput input) {
* TemporalNexusClient client, TransferInput input) {
* return client.startWorkflow(
* TransferWorkflow.class,
* TransferWorkflow::transfer,
Expand All @@ -42,6 +41,10 @@
* }
* }</pre>
*
* <p>Access information about the current invocation through {@link NexusOperationContext#getInfo()
* Nexus.getOperationContext().getInfo()}, including its cancellation token and {@linkplain
* NexusOperationInfo#getRequestId() start request ID}.
*
* <p>For custom cancel, or any other handler composition, use {@link OperationImpl} with a {@link
* TemporalOperationHandler} subclass that overrides {@link
* TemporalOperationHandler#cancelWorkflowRun}. Both annotations can coexist on the same {@link
Expand Down

This file was deleted.

Loading
Loading