Add endpoint-aware serialization for Nexus operations by JoshuaFrenchwood · Pull Request #2644 · temporalio/sdk-go

JoshuaFrenchwood · 2026-09-01T14:59:58Z

What was changed

Added caller side converter.NexusSerializationContext support for workflow-scheduled Nexus operations.
This context gives the Nexus Endpoint, Service, and operation name to the data/failure converters

Why?

This enables codecs to select serialization behavior or encryption keys by Nexus endpoint, service, or operation.

For example, workflows calling two Nexus endpoints can encrypt each endpoint’s payloads with a different key while ensuring that inputs, results, and failures are decoded with the converter selected for the corresponding operation.

Checklist

Closes
How was this tested:

Added unit/functional tests to verify that NexusSerializationContext works as expected.

Any docs updates needed?

chrsmith

Lots of nitpicks and some questions. But this all looks right. (Though I'd defer approval to someone with a little more background on the SDKs and/or stronger opinions about how any newly exported types/methods should look.)

chrsmith · 2026-09-01T19:54:40Z


 // SerializationContext provides metadata about where serialization is occurring.
 // Implementations include [WorkflowSerializationContext] for workflow-level
-// payloads, and [ActivitySerializationContext] for activity-level payloads.


Minor nit: since there are 3x different things, maybe we should use a list rather than a really long sentence? e.g.

// SerializationContext provides metadata about where serialization is occurring, // with the concrete type depending on the context. // - [WorkflowSerializationContext] for workflow-level payloads // - [ActivitySerializationContext] for activity-level payloads // - [NexusSerializationContext] for caller-side Nexus operation payloads

Also, what is a "caller-side Nexus operation payload"? Would it be more accurate or clearer to say "Nexus handlers" instead?

Thanks, I updated this to be more clear. By caller side, I meant workflows that are calling nexus operations.

chrsmith · 2026-09-01T19:56:06Z


+// NexusSerializationContext is the serialization context for caller-side Nexus
+// operation input, successful result, and failure decoding. Operation summaries
+// and user metadata use the workflow serialization context instead.


Is the typical reader of this code supposed to know what "Operation summaries" or "user metadata" are referring to? It's probably benign, but if we expect different fields of the same proto to be ran through different serializers, that sounds like a bad thing?

I removed that last sentence and made this more readable.

chrsmith · 2026-09-01T20:00:21Z

@@ -2088,7 +2094,7 @@ func (weh *workflowExecutionEventHandlerImpl) handleNexusOperationCompleted(even
 	state := command.getData().(*scheduledNexusOperation)


Nit: Is there a better name we can use here than state? We are essentially casting the command's data to the underlying "event type", right? Would something like event or eventSource be clearer?

I renamed it scheduleNexusOperation

chrsmith · 2026-09-01T20:01:10Z

 	callback func(*commonpb.Payload, error),
 	startedHandler func(opID string, e error),
 ) int64 {
+	failureConverter := params.failureConverter


Nit: This is perfectly fine as-is, but you can use cmp.Or(params.failureConverter, env.failureConverter) to simplify this type of initialization.
https://pkg.go.dev/cmp#Or

Nice! used that instead thanks

chrsmith · 2026-09-01T20:04:01Z

 		return ExecuteNexusOperationParams{}, fmt.Errorf("invalid 'operation' parameter, must be an OperationReference or a string")
 	}

+	nsc := converter.NexusSerializationContext{


Nit: For readability, maybe add a comment to group these things? What do you think of:

// Nexus context and data converters.

chrsmith · 2026-09-01T20:05:50Z

+
+const intTestNexusHMACEncoding = "binary/nexus-hmac-test"
+
+func intTestNexusContextKey(endpoint, service, operation string) string {


Nit: Is "intTest" short for integration test? If so, maybe its all fine as-is. But IMHO, something like nexusContextToCodecKey might be clearer?

Yeah intTest is integration test, I renamed it to "intTestNexusCodecKey"

chrsmith · 2026-09-01T20:10:25Z

+	ts.NoError(err)
+	var result string
+	ts.NoError(run.Get(ctx, &result))
+	ts.ElementsMatch([]string{"hmac", "zlib"}, strings.Split(result, "|"))


For readability, could we have the workflow expose a proper type rather than a string?

We want to verify that the decoded results match, but It would be great if we could also look at the raw, encoded results between the two codecs and confirm that they do NOT match. (i.e. the hmac and zlib encoders are using two different encodings for the same data.)

Is there any way we can easily verify that? Or would we need to have some sort of state smuggled out of the intTestNexusCodecSelector?

Great point. I updated this workflow to return a struct, and ts.Equal for the final result. Also at the end of the test I look in the History to verify that the encoded data does not match.

chrsmith · 2026-09-01T20:12:15Z

 ### Added

+- Added caller-side `converter.NexusSerializationContext` support for Nexus operation inputs,
+  results, and failures. Each scheduled operation retains an isolated contextual data and failure


How is this supposed to work in the long run?

This is wired up for Nexus invocations made from workflows, but what about SANOs?

If the handler-side is supposed to use the same converter, how will this actually work?

I'm just trying to understand the next few steps in getting this all working end-to-end.

Yes the long term is to have SANO support. This PR starts with Nexus calls from in workflows because the Nexus Context (service, endpoint, operation) are present. Adding SANO support and handler side will require server changes, because that context is not currently returned when a SANO result or failure is polled, or consistently propagated to Temporal entities started by Nexus handlers.

JoshuaFrenchwood requested a review from a team as a code owner September 1, 2026 14:59

JoshuaFrenchwood added 2 commits September 1, 2026 14:36

Add endpoint-aware serialization for Nexus operations

7c344c8

Updating Integration Test

e31beb5

JoshuaFrenchwood force-pushed the feature/endpoint-aware-nexus-serialization branch from 6d95b6a to e31beb5 Compare September 1, 2026 19:36

fixing failing tests

67bd1a3

chrsmith reviewed Sep 1, 2026

View reviewed changes

JoshuaFrenchwood requested a review from mavemuri September 1, 2026 20:45

Improving comments and tests

0b953f4

		@@ -2088,7 +2094,7 @@ func (weh *workflowExecutionEventHandlerImpl) handleNexusOperationCompleted(even
		state := command.getData().(*scheduledNexusOperation)


		const intTestNexusHMACEncoding = "binary/nexus-hmac-test"

		func intTestNexusContextKey(endpoint, service, operation string) string {

Uh oh!

Conversation

JoshuaFrenchwood commented Sep 1, 2026

What was changed

Why?

Checklist

Uh oh!

chrsmith left a comment

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!

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!

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!

2 participants