Skip to content

Nexus serialization context workflows activities - #2043

Open
JoshuaFrenchwood wants to merge 5 commits into
mainfrom
nexus-serialization-context-workflows-activities
Open

JoshuaFrenchwood wants to merge 5 commits into
mainfrom
nexus-serialization-context-workflows-activities

Conversation

@JoshuaFrenchwood

Copy link
Copy Markdown
Contributor

What was changed

Nexus operation handlers now propagate their NexusSerializationContext to the workflows and standalone activities they start.

  • Handler: workflow starts (including update-with-start's start) and standalone activity starts made inside a Nexus operation handler carry the context on the request.
  • Workflows: the result and closing failure are encoded with the context from InitializeWorkflow. This happens at both the converter and codec layers, including fail-workflow commands. Input, memo, signals, queries and updates keep the WorkflowSerializationContext.
  • Standalone activities: the result, all failure paths and heartbeat details are encoded with the context from the activity task, and heartbeat details are decoded with it on retry. Input keeps the ActivitySerializationContext. Heartbeat details are included because the server copies them into the heartbeat timeout failure returned to the Nexus caller.
  • New experimental activity.Info.nexus_serialization_context: for async completion, the activity passes it to the completing client, which calls AsyncActivityHandle.with_context(...). That covers complete, fail, report_cancellation and heartbeat.
  • Clients decode with the context the server returns:
    • WorkflowHandle.result() decodes the whole close event with it.
    • ActivityHandle.result() and describe() (result, outcome failure, last failure, heartbeat details) use it.
    • Standalone Nexus operation handles use it, so a handle obtained by operation ID now decodes correctly. On older servers that don't return the context, they fall back to the start request's context.
  • Unrelated, small: create_task on the workflow event loop accepts the eager_start parameter that Python 3.14 added, so newer type stubs don't report an incompatible override.
  • Tests: the dev server is bumped to v1.9.3-nexus-serialization-context, which propagates the context.

Why?

The result and failure of a workflow or standalone activity started by a Nexus handler are returned to the Nexus caller, which decodes them with the operation's NexusSerializationContext. A codec keyed on the context, for example one that encrypts per endpoint or operation, couldn't decode them when they were encoded with the workflow or activity context.

Async completion needs an explicit opt-in, because the completing client only has a task token and can't recover the context itself.

Checklist

  1. Closes

  2. How was this tested:

The tests in tests/test_serialization_context.py run on the dev server with a strict codec. It marks payloads encoded under a Nexus context and asserts if a marked payload is decoded without that context.

  • test_nexus_started_workflow_uses_nexus_context[result|failure|continue_as_new]: the caller result, plus a handle obtained by ID that relies on the server's context. It also checks that the started event carries the context, the input is unmarked and the close event is marked.
  • test_nexus_started_activity_uses_nexus_context: both attempts see Info.nexus_serialization_context, and the retry decodes the previous attempt's heartbeat details. result() and describe() decode correctly, and the result and heartbeat payloads are marked.
  • test_nexus_started_activity_failure_uses_nexus_context: result() and describe().outcome_failure() decode the failure details.
  • test_nexus_started_activity_async_completion_with_context: client heartbeat and completion via with_context(info.nexus_serialization_context).
  • test_standalone_nexus_handle_obtained_by_id_uses_server_context: now passes with the strict codec.
  1. Any docs updates needed?

@JoshuaFrenchwood
JoshuaFrenchwood requested a review from a team as a code owner October 29, 2026 18:24
@JoshuaFrenchwood JoshuaFrenchwood mentioned this pull request Oct 29, 2026
@JoshuaFrenchwood
JoshuaFrenchwood force-pushed the nexus-serialization-context-workflows-activities branch from 2f4ac89 to 01025c0 Compare October 29, 2026 18:35
Base automatically changed from update-core-nexus-serialization-context to main October 29, 2026 20:28
@tconley1428
tconley1428 force-pushed the nexus-serialization-context-workflows-activities branch from 0336837 to a72fa12 Compare October 29, 2026 20:28

This branch has not been deployed

No deployments
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.

1 participant