API surface area for worker callbacks by chrsmith · Pull Request #836 · temporalio/api

chrsmith · 2026-07-20T23:50:53Z

⚠️ This isn't meant to be merged any time soon. This is just part of the worker callbacks implementation. After the code review, I'll replace the feature/worker-callbacks branch with this.

What changed?

Adds the API surface area for the WIP worker callbacks feature.

Specifically, the changes are:

Add a completion_callbacks field to StartNexusOperationExecutionRequest. (How worker callbacks will be sent to the server.)
Introduce a new Worker variant of commonpb.Callback. (How worker callbacks will be encoded.)
Add a new notificationservice/v1/request_response.proto to define the input/output shape for worker callbacks. (The payload that will be delivered to workers.)

Why?

Today it is cumbersome to durably invoke Nexus operations and execute logic based on their results. "Worker callbacks" is a capability being developed that would allow developers to attach a Nexus operation to a SANO. Later, when the SANO reaches a terminal state, the attached Nexus operation would be invoked.

Breaking changes

None.

Server PR

TBD. The current prototype (based on the feature/worker-callbacks branch in this repo) can be found at:
https://github.com/temporalio/temporal/compare/feature/worker-callbacks?expand=1

bergundy

You're missing a new link definition to a callback on an execution.

bergundy · 2026-07-21T15:02:08Z

+        // Nexus task queue the Temporal worker is listening on.
+        //
+        // NOTE: This is not a temporal.api.taskqueue.v1.TaskQueue to avoid a circular dependency.
+        string taskqueue_name = 1;


nit: we call this field task_queue everywhere, it will generate better across languages with the underscore. Rename to task_queue_name.

Asking because I'm not sure: is it a problem that we aren't using the proper TaskQueue proto type here?

This is the full proto definition. We'd be missing out on the kind and normal_name of task queue. And just assuming it's TASK_QUEUE_KIND_NORMAL. (And never TASK_QUEUE_KIND_WORKER_COMMANDS or TASK_QUEUE_KIND_STICKY.)

Could that be a problem down the road?

bergundy · 2026-07-21T15:08:11Z

    temporal.api.sdk.v1.UserMetadata user_metadata = 16;
+
+    // Completion callbacks to be invoked once the Nexus operation reaches a terminal state.
+    repeated temporal.api.common.v1.Callback completion_callbacks = 17;


You'll need to add the full attachment support that we have for request IDs and on conflict options for workflows and activities.

Would you mind elaborating on what you mean by this? What do you mean by "full attachment" here?

I'm patterning this after the way we added completion callbacks to StartActivityExecutionRequest and StartWorkflowExecutionRequest. I see in both of those other request types there are id_conflict_policy / id_reuse_policy fields. But StartNexusOperationExecutionRequest has similar fields as well.

Are you saying that each individual commonpb.Callbacks should have its own (potentially user-supplied) callback_id ? And ID Conflict/Reuse policies supplied too? That doesn't make sense to me. Since if the SANO is accepted by Temporal, the callbacks should be accepted as well. (And I don't see any sort of UpdateNexusOperationExecution-type command, that would allow us to merge/update callbacks?)

Let's sync up on this

chrsmith · 2026-07-21T21:20:43Z

@bergundy Thanks for the review, please take another look.

Expose a new CallbackExecutionInfo proto from DescribeNexusOperationExecutionResponse. (It's a subset of what was going to be added for Manual Completion in Add Standalone Callbacks (rebase) #774.)
Add a new Callback variant of Link.

bergundy · 2026-07-23T15:11:16Z

+            string request_id  = 3;
+        }
+
+        string callback_id = 1;


There's no callback_id to refer to in all of our models.

A SANO operation could have multiple worker callbacks associated with it. So in order for the link to not be ambiguous, we need some sort of unique identifier for which callback on the SANO.

The user would be able to see those IDs on the workflowservice.CallbackExecutionInfo messages, returned from DescribeNexusOperationExecution.

Does that sound right? Or is it that we don't actually need to have callback_id here?

That's what the request ID is for.

I don't follow. Would you mind elaborating on that? ... in fact, what does NexusOperationCompletion::request_id mean in this context?

Would that be the request_id that was sent when we go and invoke the worker callback? (e.g. the nexuspb.StartOperationRequest::request_id that is sent to the worker?)

bergundy · 2026-07-23T15:13:48Z

        Activity activity = 3;
        NexusOperation nexus_operation = 4;
        Workflow workflow = 5;
+        Callback callback = 6;


Maybe just flatten the Callback into this variant? NexusOperationCompletionCallback? Or just NexusOperationCallback?

I can be convinced otherwise, but I'm inclined to keep it as-is. Let me know if you disagree.

When we later support attaching worker callbacks to Workflows and Activities, it would be kind of lame to have unique kinds of links for those. e.g. WorkflowCompletionCallback and ActivityCompletionCallback. Do we want to treat those as three different kinds of Links or just a Link to a callback, which can be pointing to different resources?

This works too.

bergundy · 2026-07-23T15:28:01Z

    temporal.api.sdk.v1.UserMetadata user_metadata = 16;
+
+    // Completion callbacks to be invoked once the Nexus operation reaches a terminal state.
+    repeated temporal.api.common.v1.Callback completion_callbacks = 17;


Let's sync up on this

…onse

chrsmith · 2026-07-24T20:34:28Z

Rebased and force-pushed. @bergundy PTAL. Though that last one re: "full attachment" will probably need a sync conversation, as I'm not sure what you're asking for there.

Here are the open questions/threads remaining:

Exposing a callback_id field on Link_Callback objects. We need that, right?
API surface area for worker callbacks #836 (comment)
Happy to have Link_NexusOperationCompletionCallback, but are you sure we want that and Link_WorkflowCompletionCallback later?
API surface area for worker callbacks #836 (comment)
Is there any problem with us only having the task queue name and not its kind?
API surface area for worker callbacks #836 (comment)
Adding "full attachment support that we have for request IDs and on conflict options". I'm not sure what that means.
API surface area for worker callbacks #836 (comment)

bergundy · 2026-07-24T22:52:05Z

+}
+
+message CallbackExecutionOutcome {
+    oneof value {
+        // The callback completed successfully. (Which may include delivering a "failed" result successfully.)
+        google.protobuf.Empty success = 1;
+        // The failure if the callback was not able to complete successfully. e.g. timed out, received an
+        // unretriable error, etc.
+        temporal.api.failure.v1.Failure failure = 2;
+    }
+}
+
+message CallbackExecutionInfo {
+    // Identifier of the callback's execution. Unique within the containing namespace.
+    string callback_id = 1;
+
+    CallbackInfo info = 2;
+    CallbackExecutionOutcome outcome = 3;
+}
+


Suggested change

}

message CallbackExecutionOutcome {

oneof value {

// The callback completed successfully. (Which may include delivering a "failed" result successfully.)

google.protobuf.Empty success = 1;

// The failure if the callback was not able to complete successfully. e.g. timed out, received an

// unretriable error, etc.

temporal.api.failure.v1.Failure failure = 2;

}

}

message CallbackExecutionInfo {

// Identifier of the callback's execution. Unique within the containing namespace.

string callback_id = 1;

CallbackInfo info = 2;

CallbackExecutionOutcome outcome = 3;

}

// TODO document me

CallbackExecutionOutcome outcome = 9;

}

message CallbackExecutionOutcome {

oneof value {

// The callback completed successfully. (Which may include delivering a "failed" result successfully.)

google.protobuf.Empty success = 1;

// The failure if the callback was not able to complete successfully. e.g. timed out, received an

// unretriable error, etc.

temporal.api.failure.v1.Failure failure = 2;

}

}

I wasn't sure how concerned we'd be with including the failure objects in CallbackInfo, so I created the separate -ExecutionInfo. But I'm happy to make the change to just add the -ExecutionOutcome as a field to CallbackInfo. (And existing callsites would just leave it blank, and maybe we'd wire through a bool include_outcome field in the request object or something.)

bergundy · 2026-07-24T22:53:09Z

+            string request_id  = 3;
+        }
+
+        string callback_id = 1;


That's what the request ID is for.

bergundy · 2026-07-24T22:53:35Z

        Activity activity = 3;
        NexusOperation nexus_operation = 4;
        Workflow workflow = 5;
+        Callback callback = 6;


This works too.

bergundy · 2026-07-24T22:54:50Z

+message OnCompleteRequest {
+
+    // The outcome of the source operation.
+    message Outcome {


Might be worth defining Outcome in common at this point.

I tried, but it would require some more refactoring since that would lead to a circular dependency between commonpb and failurepb. Maybe we could expose some other or simpler error type in the Outcome::failure case. But the failurepb.Failure seems kinda useful in how it strongly types various categories of errors.

bergundy · 2026-07-24T22:55:50Z

+
+    // Completion callbacks to be invoked once the Nexus operation reaches a terminal state.
+    // They will remain in the CALLBACK_STATE_STANDBY state until the Nexus operation is finished.
+    repeated temporal.api.callback.v1.CallbackExecutionInfo completion_callbacks = 7;


Suggested change

repeated temporal.api.callback.v1.CallbackExecutionInfo completion_callbacks = 7;

repeated temporal.api.nexusoperation.v1.CallbackInfo callbacks = 7;

And copy from

api/temporal/api/activity/v1/message.proto

Line 233 in f53963d

message CallbackInfo {

Ack, will get to in the next rev. And having different CallbackInfo objects defined in different namespaces (e.g. /activity, /nexusoperation will sidestep some other problems we might have.)

Co-authored-by: Roey Berman <roey.berman@gmail.com>

chrsmith assigned bergundy and VegetarianOrc Jul 20, 2026

bergundy reviewed Jul 21, 2026

View reviewed changes

chrsmith force-pushed the chrsmith/worker-callbacks-review branch from 334ee1f to 1329a40 Compare July 21, 2026 20:39

bergundy reviewed Jul 23, 2026

View reviewed changes

chrsmith added 4 commits July 24, 2026 13:18

API surface area for worker callbacks

1af88d7

Expose CallbackExecutionInfo from DescribeNexusOperationExecutionResp…

c074ae0

…onse

Add new Callback variant of Link

f6b3d1c

Address PR feedback

c176d77

chrsmith force-pushed the chrsmith/worker-callbacks-review branch from 1a13720 to c176d77 Compare July 24, 2026 20:33

bergundy reviewed Jul 24, 2026

View reviewed changes

Apply suggestions from code review

7278236

Co-authored-by: Roey Berman <roey.berman@gmail.com>

	repeated temporal.api.callback.v1.CallbackExecutionInfo completion_callbacks = 7;
	repeated temporal.api.nexusoperation.v1.CallbackInfo callbacks = 7;

Uh oh!

Conversation

chrsmith commented Jul 20, 2026

Uh oh!

bergundy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrsmith commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

chrsmith commented Jul 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chrsmith commented Jul 21, 2026 •

edited

Loading