Skip to content

Add workflow-side signal-with-start through system Nexus - #3154

Open
tconley1428 wants to merge 28 commits into
mainfrom
java-signal-with-start
Open

tconley1428 wants to merge 28 commits into
mainfrom
java-signal-with-start

Conversation

@tconley1428

@tconley1428 tconley1428 commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Add workflow-side signal-with-start through generated workflow-package APIs, with typed method calls, options builders, destination-aware payload conversion, and operation-specific outbound interceptor hooks. Task queue defaults to the calling workflow’s queue at invocation.

Method capture and converter scoping landed in #3213; this PR is now based directly on main. Generated bindings, system-envelope handling, payload traversal, and workflow dispatch remain here. Bindings use nexgen 0.2.12 from temporalio/nexgen#245; ordinary SDK builds use checked-in sources and do not require Rust or nexgen.

Requires a server with history.enableSignalWithStartFromWorkflow enabled. The dev-server profile enables it for coverage of signal-with-start, codecs, concurrent destinations, external storage, and replay. No server change is included here.

@tconley1428
tconley1428 changed the base branch from main to system-nexus-prerequisites November 16, 2026 18:42
@tconley1428
tconley1428 added this pull request to stack #3216 November 16, 2026 19:20
@tconley1428
tconley1428 force-pushed the java-signal-with-start branch 2 times, most recently from 7aa7309 to 1329cdc Compare November 17, 2026 19:15
Base automatically changed from system-nexus-prerequisites to main November 18, 2026 19:00
Use nexgen 0.2.12 and the explicit workflow target. Synchronize the shared WIT inputs with nexgen and regenerate the SDK bindings, including invocation-time task queue defaults.

Cover typed and name-based calls without an explicit task queue, and update regeneration and API documentation.
Enable the same dynamic configuration used by the Python samples in the SDK repository server profile. Exercise the generated task queue default in the real-server signal-with-start and replay test, and document the command for reproducing it.
@tconley1428
tconley1428 force-pushed the java-signal-with-start branch from 1329cdc to 903f6bb Compare November 18, 2026 19:06
@tconley1428
tconley1428 marked this pull request as ready for review November 18, 2026 19:09
@tconley1428
tconley1428 requested a review from a team as a code owner November 18, 2026 19:09
public abstract class WorkflowOperations {
protected WorkflowOperations() {}

private static io.temporal.workflow.SignalWithStartWorkflowRequest.Builder

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.

the constructor for the builder should be on SignalWithStartWorkflowOptions

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved defects break batch-codec round-trips, select storage for the caller rather than the destination, and mishandle encoded headers and propagated context.

3 open issues
What changed in this PR

Adds workflow-side signal-with-start through system Nexus, building on the method-capture and converter-scoping groundwork in #3213. Generated APIs integrate with the SDK’s workflow execution, interception, and payload handling.

Changes:

  • Adds typed and name-based calls, options builders, and invocation-time task queue defaults.
  • Introduces operation-specific interception, destination-aware conversion, and nested system-envelope traversal.
  • Adds generation tooling, documentation, and tests for codecs, external storage, concurrent destinations, and replay.
File Description
temporal-testing/​src/​main/​java/​io/​temporal/​testing/​TestActivityEnvironmentInternal.java Rejects workflow-only system operations in activity tests.
temporal-testing/​src/​main/​java/​io/​temporal/​testing/​internal/​TracingWorkerInterceptor.java Forwards the signal-with-start hook.
temporal-testing/​src/​main/​java/​io/​temporal/​testing/​internal/​devserver/​SdkJavaTestServerProfile.java Enables server-side signal-with-start support.
temporal-serviceclient/​src/​test/​java/​io/​temporal/​internal/​payload/​visitor/​SystemNexusPayloadTest.java Tests nested envelope traversal and validation.
temporal-serviceclient/​src/​test/​java/​io/​temporal/​internal/​payload/​gen/​ProtoClosureRootTest.java Tests explicit protobuf roots and reachability.
temporal-serviceclient/​src/​payloadGenerators/​java/​io/​temporal/​internal/​payload/​visitor/​gen/​PayloadVisitorGenerator.java Generates visitors and registries for system roots.
temporal-serviceclient/​src/​payloadGenerators/​java/​io/​temporal/​internal/​payload/​gen/​ProtoClosure.java Supports explicit message roots.
temporal-serviceclient/​src/​main/​java/​io/​temporal/​internal/​payload/​visitor/​Traversal.java Traverses and repacks marked system envelopes.
temporal-serviceclient/​src/​main/​java/​io/​temporal/​internal/​payload/​visitor/​SystemNexusPayloads.java Packs and validates protobuf envelopes.
temporal-serviceclient/​build.gradle Supplies system roots to visitor generation.
temporal-sdk/​src/​test/​java/​io/​temporal/​workflow/​TypedWorkflowMethodCaptureTest.java Tests retry and cron annotation merging.
temporal-sdk/​src/​test/​java/​io/​temporal/​workflow/​TemporalModelConvertersTest.java Tests versioning override conversion.
temporal-sdk/​src/​test/​java/​io/​temporal/​workflow/​nexus/​SystemSignalWithStartIntegrationTest.java Exercises real-server execution, codecs, storage, and replay.
temporal-sdk/​src/​test/​java/​io/​temporal/​workflow/​nexus/​SignalWithStartWorkflowTest.java Tests generated calls, identity rules, and defaults.
temporal-sdk/​src/​test/​java/​io/​temporal/​internal/​payload/​storage/​ExternalStorageRunnerTest.java Tests offloading nested payloads only.
temporal-sdk/​src/​test/​java/​io/​temporal/​internal/​nexus/​system/​SystemNexusDataConverterTest.java Tests converter scopes, envelopes, and destination contexts.
temporal-sdk/​src/​main/​nexus/​workflow-service.wit Defines the operation and generation directives.
temporal-sdk/​src/​main/​nexus/​SIGNAL_WITH_START.md Documents usage, behavior, and integration tests.
temporal-sdk/​src/​main/​nexus/​README.md Documents binding generation and architecture.
temporal-sdk/​src/​main/​nexus/​deps/​nexus-temporal-types/​model.wit Defines shared model and callable mappings.
temporal-sdk/​src/​main/​java/​io/​temporal/​workflow/​Workflow.java Exposes inherited generated operations.
temporal-sdk/​src/​main/​java/​io/​temporal/​workflow/​TemporalModelConverters.java Implements SDK-owned capture and conversion helpers.
temporal-sdk/​src/​main/​java/​io/​temporal/​internal/​sync/​SyncWorkflowContext.java Executes system operations with destination-aware converters.
temporal-sdk/​src/​main/​java/​io/​temporal/​internal/​sync/​NexusServiceStubImpl.java Routes system operations through dedicated hooks.
temporal-sdk/​src/​main/​java/​io/​temporal/​internal/​nexus/​system/​SystemNexusDataConverter.java Separates system envelopes from user conversion.
temporal-sdk/​src/​main/​java/​io/​temporal/​common/​interceptors/​WorkflowOutboundCallsInterceptorBase.java Inherits generated hook forwarding.
temporal-sdk/​src/​main/​java/​io/​temporal/​common/​interceptors/​WorkflowOutboundCallsInterceptor.java Includes system-operation interception.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​WorkflowService.java Defines the generated Nexus service interface.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​WorkflowOperations.java Provides generated signal-with-start overloads.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​UserMetadata.java Represents and converts static workflow metadata.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​SystemNexusWorkflowOutboundInterceptor.java Defines typed hooks, forwarding, and terminal dispatch.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​SystemNexusOperations.java Dispatches operations and selects serialization contexts.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​system-nexus-roots.txt Lists request and response protobuf roots.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​SignalWithStartWorkflowResponse.java Provides the response model and conversion.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​SignalWithStartWorkflowRequest.java Provides the request model and conversion.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​SignalWithStartWorkflowOptions.java Provides reusable operation options.
temporal-sdk/​src/​main/​generated/​io/​temporal/​workflow/​NexgenRuntime.java Supplies generated sequence-decoding support.
temporal-sdk/​build.gradle Registers checked-in sources and explicit regeneration.
CHANGELOG.md Announces workflow-side signal-with-start.

Review effort: Balanced

Comment on lines +128 to +129
Message.Builder inner = SystemNexusPayloads.unpack(value);
dispatch(inner);
@Quinn-With-Two-Ns

Copy link
Copy Markdown
Contributor

AI flagged two other issues that survived my review

1. P2 · External storage attributes the payloads to the caller. The visitor unwraps the system request and offloads its workflow input, signal input, and memo. WorkflowWorker keeps the caller as the storage target for all Nexus commands, so selectors and drivers receive the caller’s ID and workflow type for data destined for another workflow. A selector that routes by workflow type can put both destinations’ payloads in the caller’s storage. Derive the target from the embedded request and assert the target IDs in the existing concurrent-destination test.
4. P3 · The name-based overload dispatches an empty workflow ID. setId("") passes requireNonNull and reaches the outbound hook, although the WIT requires a nonempty ID and the typed path enforces it. Apply the same validation before dispatch and assert that an empty ID schedules no operation.

* these invocations. Supply all other fields through the required options object. Fields with
* declared merge-from-function hooks merge explicit values with the named callable's metadata.
*/
public static <WorkflowResult> io.temporal.workflow.ExternalWorkflowStub signalWithStartWorkflow(

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.

Can we also clarify when this returns? Like users often get burnt when starting a child workflow because when the call returns doesn't mean the child workflow has actually been started


/** Signal a workflow, starting it first if needed. */
@SuppressWarnings({"unchecked", "rawtypes"})
public final class SignalWithStartWorkflowOptions {

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.

few notes on the builder

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.

3 participants