Skip to content

💥 [BREAKING CHANGE] Rename Nexus Operation classes used in a workflow in preparation for Stand alone Nexus operations #619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Quinn-With-Two-Ns merged 5 commits into from
Mar 10, 2026
Merged

💥 [BREAKING CHANGE] Rename Nexus Operation classes used in a workflow in preparation for Stand alone Nexus operations #619

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
beb9e02
Rename Nexus classes in Workflow
Quinn-With-Two-Ns Feb 26, 2026
08fd7b1
Fix rename
Quinn-With-Two-Ns Feb 26, 2026
9e788a6
keep span labels the same
Quinn-With-Two-Ns Feb 26, 2026
96eaee0
Merge branch 'main' into issue-618
Quinn-With-Two-Ns Mar 10, 2026
e01b7bd
Fix CI tests
Quinn-With-Two-Ns Mar 10, 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
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -588,12 +588,12 @@ Some things to note about the above code:

#### Invoking Nexus Operations

* Nexus operations are started by first obtaining a Nexus client for a service via `Workflow.CreateNexusClient`, then
* Nexus operations are started by first obtaining a Nexus client for a service via `Workflow.CreateNexusWorkflowClient`, then
invoking `StartNexusOperationAsync` on it which accepts a lambda expression for the call on the service.
* Non-type-safe forms of `Workflow.CreateNexusClient` and `StartNexusOperationAsync` exist that just accept string
* Non-type-safe forms of `Workflow.CreateNexusWorkflowClient` and `StartNexusOperationAsync` exist that just accept string
service and operation names.
* Nexus client and operation options are simple classes optionally provided as the last parameter.
* Result of a Nexus operation starting is a `NexusOperationHandle` which has the operation token and `GetResultAsync`
* Result of a Nexus operation starting is a `NexusWorkflowOperationHandle` which has the operation token and `GetResultAsync`
for getting the result.
* The task for starting a Nexus operation does not complete until the operation has actually started.
* A shortcut of `ExecuteNexusOperationAsync` is available which is `StartNexusOperationAsync` + `GetResultAsync` for
Expand Down
2 changes: 1 addition & 1 deletion src/Temporalio.Extensions.OpenTelemetry/TracingInterceptor.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -700,7 +700,7 @@ public override Task<ChildWorkflowHandle<TWorkflow, TResult>> StartChildWorkflow
return base.StartChildWorkflowAsync<TWorkflow, TResult>(input);
}

public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
public override Task<NexusWorkflowOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
StartNexusOperationInput input)
{
var headers = StartWorkflowActivityOnHeaders(
Expand Down
4 changes: 2 additions & 2 deletions src/Temporalio/Worker/Interceptors/StartNexusOperationInput.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ namespace Temporalio.Worker.Interceptors
/// <remarks>WARNING: Nexus support is experimental.</remarks>
public record StartNexusOperationInput(
string Service,
NexusClientOptions ClientOptions,
NexusWorkflowClientOptions ClientOptions,
string OperationName,
object? Arg,
NexusOperationOptions Options,
NexusWorkflowOperationOptions Options,
IDictionary<string, string>? Headers);
}
2 changes: 1 addition & 1 deletion src/Temporalio/Worker/Interceptors/WorkflowOutboundInterceptor.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ public virtual Task<ChildWorkflowHandle<TWorkflow, TResult>> StartChildWorkflowA
/// <param name="input">Input details of the call.</param>
/// <returns>Operation handle.</returns>
/// <remarks>WARNING: Nexus support is experimental.</remarks>
public virtual Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
public virtual Task<NexusWorkflowOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
StartNexusOperationInput input) => Next.StartNexusOperationAsync<TResult>(input);
}
}
40 changes: 20 additions & 20 deletions src/Temporalio/Worker/WorkflowInstance.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -406,12 +406,12 @@ public ContinueAsNewException CreateContinueAsNewException(
Headers: null));

/// <inheritdoc/>
public NexusClient CreateNexusClient(string service, NexusClientOptions options) =>
new NexusClientImpl(this, service, options);
public NexusWorkflowClient CreateNexusWorkflowClient(string service, NexusWorkflowClientOptions options) =>
new NexusWorkflowClientImpl(this, service, options);

/// <inheritdoc/>
public NexusClient<TService> CreateNexusClient<TService>(NexusClientOptions options) =>
new NexusClientImpl<TService>(this, options);
public NexusWorkflowClient<TService> CreateNexusWorkflowClient<TService>(NexusWorkflowClientOptions options) =>
new NexusWorkflowClientImpl<TService>(this, options);

/// <inheritdoc/>
public Task DelayWithOptionsAsync(DelayOptions options) =>
Expand Down Expand Up @@ -2540,7 +2540,7 @@ public override Task<ChildWorkflowHandle<TWorkflow, TResult>> StartChildWorkflow
}

/// <inheritdoc/>
public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
public override Task<NexusWorkflowOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
StartNexusOperationInput input)
{
var token = input.Options.CancellationToken ?? instance.CancellationToken;
Expand All @@ -2551,7 +2551,7 @@ public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TRe
// TemporalException.IsCanceledException helper).
if (token.IsCancellationRequested)
{
return Task.FromException<NexusOperationHandle<TResult>>(
return Task.FromException<NexusWorkflowOperationHandle<TResult>>(
new CanceledFailureException("Nexus operation cancelled before scheduled"));
}

Expand Down Expand Up @@ -2591,7 +2591,7 @@ public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TRe
}
instance.AddCommand(workflowCommand);

var handleSource = new TaskCompletionSource<NexusOperationHandle<TResult>>();
var handleSource = new TaskCompletionSource<NexusWorkflowOperationHandle<TResult>>();
var pending = new PendingNexusOperationInfo(
StartCompletionSource: new(),
ResultCompletionSource: new());
Expand Down Expand Up @@ -2619,7 +2619,7 @@ public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TRe

// If there is a start sync fail, we have to fail the handle task and
// there's nothing more we can do here
var handle = new NexusOperationHandleImpl<TResult>(
var handle = new NexusWorkflowOperationHandleImpl<TResult>(
payloadConverter,
// TODO(cretz): Support Nexus serialization context, ideally not
// creating failure converter with context until actually needed
Expand Down Expand Up @@ -2925,11 +2925,11 @@ public override Task CancelAsync() =>
instance.outbound.Value.CancelExternalWorkflowAsync(new(Id: Id, RunId: RunId));
}

private class NexusClientImpl : NexusClient
private class NexusWorkflowClientImpl : NexusWorkflowClient
{
private readonly WorkflowInstance instance;

public NexusClientImpl(WorkflowInstance instance, string service, NexusClientOptions options)
public NexusWorkflowClientImpl(WorkflowInstance instance, string service, NexusWorkflowClientOptions options)
{
this.instance = instance;
Service = service;
Expand All @@ -2938,10 +2938,10 @@ public NexusClientImpl(WorkflowInstance instance, string service, NexusClientOpt

public override string Service { get; }

public override NexusClientOptions Options { get; }
public override NexusWorkflowClientOptions Options { get; }

public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
string operationName, object? arg, NexusOperationOptions? options = null) =>
public override Task<NexusWorkflowOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
string operationName, object? arg, NexusWorkflowOperationOptions? options = null) =>
instance.outbound.Value.StartNexusOperationAsync<TResult>(new(
Service: Service,
ClientOptions: Options,
Expand All @@ -2951,11 +2951,11 @@ public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TRe
Headers: null));
}

private class NexusClientImpl<TService> : NexusClient<TService>
private class NexusWorkflowClientImpl<TService> : NexusWorkflowClient<TService>
{
private readonly WorkflowInstance instance;

public NexusClientImpl(WorkflowInstance instance, NexusClientOptions options)
public NexusWorkflowClientImpl(WorkflowInstance instance, NexusWorkflowClientOptions options)
{
this.instance = instance;
ServiceDefinition = ServiceDefinition.FromType<TService>();
Expand All @@ -2964,10 +2964,10 @@ public NexusClientImpl(WorkflowInstance instance, NexusClientOptions options)

public override ServiceDefinition ServiceDefinition { get; }

public override NexusClientOptions Options { get; }
public override NexusWorkflowClientOptions Options { get; }

public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
string operationName, object? arg, NexusOperationOptions? options = null) =>
public override Task<NexusWorkflowOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
string operationName, object? arg, NexusWorkflowOperationOptions? options = null) =>
instance.outbound.Value.StartNexusOperationAsync<TResult>(new(
Service: Service,
ClientOptions: Options,
Expand All @@ -2977,12 +2977,12 @@ public override Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TRe
Headers: null));
}

private class NexusOperationHandleImpl<TResult> : NexusOperationHandle<TResult>
private class NexusWorkflowOperationHandleImpl<TResult> : NexusWorkflowOperationHandle<TResult>
{
private readonly IPayloadConverter payloadConverter;
private readonly IFailureConverter failureConverter;

public NexusOperationHandleImpl(
public NexusWorkflowOperationHandleImpl(
IPayloadConverter payloadConverter,
IFailureConverter failureConverter,
string? operationToken)
Expand Down
8 changes: 4 additions & 4 deletions src/Temporalio/Workflows/IWorkflowContext.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,20 +155,20 @@ ContinueAsNewException CreateContinueAsNewException(
string workflow, IReadOnlyCollection<object?> args, ContinueAsNewOptions? options);

/// <summary>
/// Backing call for <see cref="Workflow.CreateNexusClient(string, NexusClientOptions)"/>.
/// Backing call for <see cref="Workflow.CreateNexusWorkflowClient(string, NexusWorkflowClientOptions)"/>.
/// </summary>
/// <param name="service">Service name.</param>
/// <param name="options">Options.</param>
/// <returns>Nexus client.</returns>
NexusClient CreateNexusClient(string service, NexusClientOptions options);
NexusWorkflowClient CreateNexusWorkflowClient(string service, NexusWorkflowClientOptions options);

/// <summary>
/// Backing call for <see cref="Workflow.CreateNexusClient{TService}(NexusClientOptions)"/>.
/// Backing call for <see cref="Workflow.CreateNexusWorkflowClient{TService}(NexusWorkflowClientOptions)"/>.
/// </summary>
/// <typeparam name="TService">Service type.</typeparam>
/// <param name="options">Options.</param>
/// <returns>Nexus client.</returns>
NexusClient<TService> CreateNexusClient<TService>(NexusClientOptions options);
NexusWorkflowClient<TService> CreateNexusWorkflowClient<TService>(NexusWorkflowClientOptions options);

/// <summary>
/// Backing call for <see cref="Workflow.DelayWithOptionsAsync(DelayOptions)" /> and
Expand Down
46 changes: 23 additions & 23 deletions src/Temporalio/Workflows/NexusClient.cs → ...mporalio/Workflows/NexusWorkflowClient.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ namespace Temporalio.Workflows
/// Client for making Nexus service calls from a workflow.
/// </summary>
/// <remarks>WARNING: Nexus support is experimental.</remarks>
public abstract class NexusClient
public abstract class NexusWorkflowClient
{
/// <summary>
/// Gets the service name.
Expand All @@ -23,38 +23,38 @@ public abstract class NexusClient
/// <summary>
/// Gets the client options. Should not be mutated.
/// </summary>
public abstract NexusClientOptions Options { get; }
public abstract NexusWorkflowClientOptions Options { get; }

/// <summary>
/// Shortcut for
/// <see cref="StartNexusOperationAsync(string, object?, NexusOperationOptions?)"/>
/// <see cref="StartNexusOperationAsync(string, object?, NexusWorkflowOperationOptions?)"/>
/// +
/// <see cref="NexusOperationHandle.GetResultAsync"/>.
/// <see cref="NexusWorkflowOperationHandle.GetResultAsync"/>.
/// </summary>
/// <param name="operationName">Operation name to start.</param>
/// <param name="arg">Operation argument.</param>
/// <param name="options">Operation options.</param>
/// <returns>Task representing completion of the Nexus operation.</returns>
public async Task ExecuteNexusOperationAsync(
string operationName, object? arg, NexusOperationOptions? options = null)
string operationName, object? arg, NexusWorkflowOperationOptions? options = null)
{
var handle = await StartNexusOperationAsync(operationName, arg, options).ConfigureAwait(true);
await handle.GetResultAsync().ConfigureAwait(true);
}

/// <summary>
/// Shortcut for
/// <see cref="StartNexusOperationAsync{TResult}(string, object?, NexusOperationOptions?)"/>
/// <see cref="StartNexusOperationAsync{TResult}(string, object?, NexusWorkflowOperationOptions?)"/>
/// +
/// <see cref="NexusOperationHandle{TResult}.GetResultAsync"/>.
/// <see cref="NexusWorkflowOperationHandle{TResult}.GetResultAsync"/>.
/// </summary>
/// <typeparam name="TResult">Operation result type.</typeparam>
/// <param name="operationName">Operation name to start.</param>
/// <param name="arg">Operation argument.</param>
/// <param name="options">Operation options.</param>
/// <returns>Task with the result of the Nexus operation.</returns>
public async Task<TResult> ExecuteNexusOperationAsync<TResult>(
string operationName, object? arg, NexusOperationOptions? options = null)
string operationName, object? arg, NexusWorkflowOperationOptions? options = null)
{
var handle = await StartNexusOperationAsync<TResult>(operationName, arg, options).ConfigureAwait(true);
return await handle.GetResultAsync().ConfigureAwait(true);
Expand All @@ -67,8 +67,8 @@ public async Task<TResult> ExecuteNexusOperationAsync<TResult>(
/// <param name="arg">Operation argument.</param>
/// <param name="options">Operation options.</param>
/// <returns>Handle to the started operation once started.</returns>
public async Task<NexusOperationHandle> StartNexusOperationAsync(
string operationName, object? arg, NexusOperationOptions? options = null) =>
public async Task<NexusWorkflowOperationHandle> StartNexusOperationAsync(
string operationName, object? arg, NexusWorkflowOperationOptions? options = null) =>
await StartNexusOperationAsync<ValueTuple>(operationName, arg, options).ConfigureAwait(true);

/// <summary>
Expand All @@ -79,12 +79,12 @@ public async Task<NexusOperationHandle> StartNexusOperationAsync(
/// <param name="arg">Operation argument.</param>
/// <param name="options">Operation options.</param>
/// <returns>Handle to the started operation once started.</returns>
public abstract Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
string operationName, object? arg, NexusOperationOptions? options = null);
public abstract Task<NexusWorkflowOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
string operationName, object? arg, NexusWorkflowOperationOptions? options = null);
}

/// <inheritdoc />
public abstract class NexusClient<TService> : NexusClient
public abstract class NexusWorkflowClient<TService> : NexusWorkflowClient
{
/// <summary>
/// Gets the service name.
Expand All @@ -98,34 +98,34 @@ public abstract class NexusClient<TService> : NexusClient

/// <summary>
/// Shortcut for
/// <see cref="StartNexusOperationAsync(Expression{Action{TService}}, NexusOperationOptions?)"/>
/// <see cref="StartNexusOperationAsync(Expression{Action{TService}}, NexusWorkflowOperationOptions?)"/>
/// +
/// <see cref="NexusOperationHandle.GetResultAsync"/>.
/// <see cref="NexusWorkflowOperationHandle.GetResultAsync"/>.
/// </summary>
/// <param name="operationStartCall">Invocation of operation without a result.</param>
/// <param name="options">Operation options.</param>
/// <returns>Task with the result of the Nexus operation.</returns>
public async Task ExecuteNexusOperationAsync(
Expression<Action<TService>> operationStartCall,
NexusOperationOptions? options = null)
NexusWorkflowOperationOptions? options = null)
{
var handle = await StartNexusOperationAsync(operationStartCall, options).ConfigureAwait(true);
await handle.GetResultAsync().ConfigureAwait(true);
}

/// <summary>
/// Shortcut for
/// <see cref="StartNexusOperationAsync{TResult}(Expression{Func{TService, TResult}}, NexusOperationOptions?)"/>
/// <see cref="StartNexusOperationAsync{TResult}(Expression{Func{TService, TResult}}, NexusWorkflowOperationOptions?)"/>
/// +
/// <see cref="NexusOperationHandle{TResult}.GetResultAsync"/>.
/// <see cref="NexusWorkflowOperationHandle{TResult}.GetResultAsync"/>.
/// </summary>
/// <typeparam name="TResult">Operation result type.</typeparam>
/// <param name="operationStartCall">Invocation of operation with a result.</param>
/// <param name="options">Operation options.</param>
/// <returns>Task with the result of the Nexus operation.</returns>
public async Task<TResult> ExecuteNexusOperationAsync<TResult>(
Expression<Func<TService, TResult>> operationStartCall,
NexusOperationOptions? options = null)
NexusWorkflowOperationOptions? options = null)
{
var handle = await StartNexusOperationAsync(operationStartCall, options).ConfigureAwait(true);
return await handle.GetResultAsync().ConfigureAwait(true);
Expand All @@ -137,9 +137,9 @@ public async Task<TResult> ExecuteNexusOperationAsync<TResult>(
/// <param name="operationStartCall">Invocation of operation without a result.</param>
/// <param name="options">Operation options.</param>
/// <returns>Handle to the started operation once started.</returns>
public Task<NexusOperationHandle> StartNexusOperationAsync(
public Task<NexusWorkflowOperationHandle> StartNexusOperationAsync(
Expression<Action<TService>> operationStartCall,
NexusOperationOptions? options = null)
NexusWorkflowOperationOptions? options = null)
{
var (method, args) = ExpressionUtil.ExtractCall(operationStartCall);
// Find name from method
Expand All @@ -163,9 +163,9 @@ public Task<NexusOperationHandle> StartNexusOperationAsync(
/// <param name="operationStartCall">Invocation of operation with a result.</param>
/// <param name="options">Operation options.</param>
/// <returns>Handle to the started operation once started.</returns>
public Task<NexusOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
public Task<NexusWorkflowOperationHandle<TResult>> StartNexusOperationAsync<TResult>(
Expression<Func<TService, TResult>> operationStartCall,
NexusOperationOptions? options = null)
NexusWorkflowOperationOptions? options = null)
{
var (method, args) = ExpressionUtil.ExtractCall(operationStartCall);
// Find name from method
Expand Down
Loading