Worker Versioning Annotations & Options #2463

Sushisource · 2025-03-31T23:33:30Z

What was changed

Added worker options for the latest iteration of the worker versioning feature, as well as annotations for workflow methods to specify their behavior.

Why?

New feature!

Checklist

Closes Support New Worker Versioning API #2458
How was this tested:
Added tests
Any docs updates needed?

temporal-sdk/src/main/java/io/temporal/internal/worker/WorkerVersioningOptions.java

temporal-sdk/src/main/java/io/temporal/worker/WorkerOptions.java

Quinn-With-Two-Ns · 2025-03-31T23:52:08Z

Please make sure you also test Spring boot

temporal-sdk/src/main/java/io/temporal/internal/worker/WorkerVersioningOptions.java

Quinn-With-Two-Ns · 2025-03-31T23:53:30Z

temporal-sdk/src/main/java/io/temporal/internal/sync/POJOWorkflowImplementationFactory.java

+      VersioningBehavior versioningBehavior;
+      try {
+        implMethod =
+            workflowImplementationClass.getMethod(method.getName(), method.getParameterTypes());


I think this logic can be move to the metadata package for implementations

temporal-testing/src/main/java/io/temporal/testing/TestWorkflowRule.java

temporal-sdk/src/test/java/io/temporal/worker/WorkerVersioningTest.java

temporal-sdk/src/main/java/io/temporal/worker/WorkerDeploymentOptions.java

temporal-sdk/src/main/java/io/temporal/worker/WorkerOptions.java

Sushisource · 2025-04-01T00:04:09Z

Please make sure you also test Spring boot

Do you mean configuring the worker options via config files?

Quinn-With-Two-Ns · 2025-04-01T00:07:03Z

Do you mean configuring the worker options via config files?

Yes and that our auto discovery picks up the annotation. Basically that is works E2E.

Quinn-With-Two-Ns · 2025-04-01T00:11:02Z

temporal-sdk/src/test/java/io/temporal/worker/WorkerVersioningTest.java

+    return Eventually.assertEventually(
+        Duration.ofSeconds(15),
+        () -> {
+          DescribeWorkerDeploymentResponse resp =


Don't we need a high level deployment client? Go has that.

No, we're not including that as part of the initial functionality

cretz · 2025-04-01T13:41:57Z

temporal-sdk/src/main/java/io/temporal/common/WorkerDeploymentVersion.java

+  /**
+   * @return The canonical string representation of this worker deployment version.
+   */
+  public String toCanonicalString() {
+    return deploymentName + "." + buildId;
+  }


For this specific class, I think just having this be the toString instead of the generated one below would be fine

I prefer the current approach since the canonical format is different then the standard toString implementation

Meh, not sure there is such thing as a "standard" toString implementation, especially for a basic dot-delimited tuple like this. Same as there isn't a standard builder expectation for such a simple class. Having said that, I don't mind if we keep them separate.

Yeah, I looked into this when I wrote it and it seems the consensus is that toString is more for debugging than canonical representations

temporal-sdk/src/main/java/io/temporal/common/WorkerDeploymentVersion.java

temporal-sdk/src/main/java/io/temporal/common/VersioningBehavior.java

cretz · 2025-04-01T13:45:48Z

temporal-sdk/src/main/java/io/temporal/common/VersioningBehavior.java

+   * required to specify a behavior. See {@link
+   * io.temporal.worker.WorkerOptions.Builder#setDeploymentOptions(WorkerDeploymentOptions)}.
+   */
+  VERSIONING_BEHAVIOR_UNSPECIFIED,


Should we represent the absence of a versioning behavior as null instead of unspecified? If we do represent it as unspecified, can you confirm that all places we return this value to the user have it as non-null unspecified when unset?

Yeah, that's the case. (with the minor exception of the one workflow method metadata thing where it makes sense that it should be able to represent both, because it needs to distinguish un-annotated).

👍 So long as we never give this value back to the user as null and always give it back as unspecified, works for me

cretz · 2025-04-01T13:51:21Z

temporal-sdk/src/main/java/io/temporal/common/WorkerDeploymentVersion.java

Is there an issue tracking the client-side changes? Specifically, version info for list, describe, and scheduling, and the new versioning calls on the client. (asking at top of this file because this stuff is easier in a thread than PR comment and there's no better place)

temporal-sdk/src/main/java/io/temporal/worker/WorkerOptions.java

cretz · 2025-04-01T13:55:39Z

temporal-sdk/src/main/java/io/temporal/workflow/WorkflowVersioningBehavior.java

+ * implementations, not interfaces.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)


I thought this annotation would be on the class not the run method. I also expect it to be a workflow/class-level setting in other SDKs.

Being on the workflow method is correct. Workflow implementations can contain multiple workflow methods

Hrmm, my concern is that versioning applies to the entire workflow and all of its code, not just its primary method. But knowing that Java is a bit unique here and in every other SDK this versioning setting will apply to the workflow code as a whole and not just the entry point is probably ok, if unfortunate.

The Method is the workflow, a class can contain multiple unrelated workflows

The method is only part of the workflow, there is lots of code that makes up a workflow. We can only hope that when they use versioning and incompatibly change a signal handler, they remember to update the versioning enum on all primary workflow methods and not just one. But I figure multi-workflow-method workflow classes are probably not that common.

Quinn-With-Two-Ns · 2025-04-01T14:49:16Z

We also need to add support for DynamicWorkflows, I think it can be a method on the interface like void getWorkflowVersioningBehavior() WorkflowVersioningBehavior with a default

Quinn-With-Two-Ns · 2025-04-02T22:04:23Z

...e/src/test/java/io/temporal/spring/boot/autoconfigure/workerversioning/TestWorkflowImpl.java

+import io.temporal.workflow.WorkflowVersioningBehavior;
+import org.springframework.context.ConfigurableApplicationContext;
+
+@WorkflowImpl(workers = "mainWorker")


Damn Springboot taking this great annotation name for itself hehe

Quinn-With-Two-Ns · 2025-04-02T22:10:07Z

temporal-sdk/src/main/java/io/temporal/common/metadata/POJOWorkflowImplMetadata.java

+   */
+  @Experimental
+  @Nullable
+  public static VersioningBehavior getVersioningBehaviorForMethod(


We may want to make this a bit more generic if we plan to add other annotations to workflow impl. methods. Since this is experimental I am fine leaving it as is.

Sushisource requested a review from a team as a code owner March 31, 2025 23:33

Sushisource force-pushed the versioning-annotations branch 2 times, most recently from a48d6b9 to ef1b574 Compare March 31, 2025 23:41

Sushisource commented Mar 31, 2025

View reviewed changes

temporal-sdk/src/main/java/io/temporal/internal/worker/WorkerVersioningOptions.java Outdated Show resolved Hide resolved

Sushisource commented Mar 31, 2025

View reviewed changes

temporal-sdk/src/main/java/io/temporal/worker/WorkerOptions.java Outdated Show resolved Hide resolved

Sushisource added 7 commits March 31, 2025 16:49

Add initial classes / tests

cacbcb3

Basic polling

1542d02

Flesh out test and attach to task completions

355b52f

Require annotations when versioning is on

4c4c888

Add ramp test

3d013e2

Add missing experimental annotations / licenses

1c52169

TODO fix

0e6eefd

Sushisource force-pushed the versioning-annotations branch from ef1b574 to 0e6eefd Compare March 31, 2025 23:49

Quinn-With-Two-Ns reviewed Apr 1, 2025

View reviewed changes

Avoid potential null deref in unit tests

b1771a8

cretz reviewed Apr 1, 2025

View reviewed changes

Sushisource added 3 commits April 1, 2025 15:36

Review comments

b9130ac

Return errors from test server

60f0c80

Support Spring

a58ce73

Sushisource changed the title ~~Worker Versionng Annotations & Options~~ Worker Versioning Annotations & Options Apr 2, 2025

Sushisource force-pushed the versioning-annotations branch from 7fd5821 to 62d7d58 Compare April 2, 2025 21:03

Sushisource added 3 commits April 2, 2025 14:04

Make work w/ dynamic workflows

12c74fd

License format again

970b092

Enable versioning in dynamic config

dc248a0

Sushisource force-pushed the versioning-annotations branch from 62d7d58 to dc248a0 Compare April 2, 2025 21:04

Remove deprecation todo

5af7560

cretz approved these changes Apr 2, 2025

View reviewed changes

Quinn-With-Two-Ns reviewed Apr 2, 2025

View reviewed changes

Quinn-With-Two-Ns approved these changes Apr 2, 2025

View reviewed changes

Sushisource force-pushed the versioning-annotations branch from 1199b57 to db3b822 Compare April 2, 2025 22:24

Sushisource enabled auto-merge (squash) April 2, 2025 22:24

Fix spring test still running under test server when it shouldn't

928da52

Sushisource force-pushed the versioning-annotations branch from db3b822 to 928da52 Compare April 2, 2025 22:37

Merge branch 'master' into versioning-annotations

47af3eb

Sushisource merged commit b3b7806 into temporalio:master Apr 2, 2025
8 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Worker Versioning Annotations & Options #2463

Worker Versioning Annotations & Options #2463

Sushisource commented Mar 31, 2025

Quinn-With-Two-Ns commented Mar 31, 2025

Quinn-With-Two-Ns Mar 31, 2025

Sushisource commented Apr 1, 2025

Quinn-With-Two-Ns commented Apr 1, 2025

Quinn-With-Two-Ns Apr 1, 2025

Sushisource Apr 1, 2025

cretz Apr 1, 2025

Quinn-With-Two-Ns Apr 1, 2025

cretz Apr 1, 2025

Sushisource Apr 1, 2025 •

edited

Loading

cretz Apr 1, 2025

Sushisource Apr 1, 2025

cretz Apr 2, 2025

cretz Apr 1, 2025

Sushisource Apr 2, 2025

cretz Apr 1, 2025

Quinn-With-Two-Ns Apr 1, 2025

cretz Apr 1, 2025 •

edited

Loading

Quinn-With-Two-Ns Apr 1, 2025

cretz Apr 1, 2025 •

edited

Loading

Quinn-With-Two-Ns commented Apr 1, 2025

Quinn-With-Two-Ns Apr 2, 2025

Quinn-With-Two-Ns Apr 2, 2025

Worker Versioning Annotations & Options #2463

Worker Versioning Annotations & Options #2463

Conversation

Sushisource commented Mar 31, 2025

What was changed

Why?

Checklist

Quinn-With-Two-Ns commented Mar 31, 2025

Choose a reason for hiding this comment

Sushisource commented Apr 1, 2025

Quinn-With-Two-Ns commented Apr 1, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sushisource Apr 1, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cretz Apr 1, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cretz Apr 1, 2025 • edited Loading

Choose a reason for hiding this comment

Quinn-With-Two-Ns commented Apr 1, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sushisource Apr 1, 2025 •

edited

Loading

cretz Apr 1, 2025 •

edited

Loading

cretz Apr 1, 2025 •

edited

Loading