change Version to struct, prevent misconfiguration of VersioningOverride (#579)

_**READ BEFORE MERGING:** All PRs require approval by both Server AND
SDK teams before merging! This is why the number of required approvals
is "2" and not "1"--two reviewers from the same team is NOT sufficient.
If your PR is not approved by someone in BOTH teams, it may be summarily
reverted._

What changed?
- Make override a one of and add different pinned override types.
- Change version from string to struct
- Make nil Version represent "send tasks away from versioned workers and
to unversioned workers"


Why?
- To prevent misconfiguration and to expand the override definition to
accommodate the new PinnedUntilContinueAsNew behaviors.
- Using a string to represent structured data, whose subfields
frequently need to be considered separately, is brittle and not good for
anyone using it. Struct is better.
- "unversioned version" is contradictory, and nil is a nice way to
represent that the versioning story of a task queue is no longer in the
control of the Deployment whose `RoutingConfig` you are reading.


<!-- Are there any breaking changes on binary or code level? -->
Variables are being deprecated, but the content of the code is not
changing.
The idea of "Unset Ramp" having a separate meaning from "0% Ramp" is
removed. 0% ramp now is the only way to have "no ramp" / 100% of traffic
going to Current Version. Nil `ramping_deployment_version` + non-zero
`ramping_version_percentage` is the way to ramp traffic to unversioned
workers.

The SDK interface for this could look like:
```
deployment := client.GetHandle(deploymentName)

// set current to a version
deployment.SetCurrentVersion(buildId) -> current set to deploymentName/buildId
deployment.UnsetCurrentVersion() -> current set to nil

// set current to unversioned
deployment.UnsetCurrentVersion() -> current set to nil


deployment.SetRampingVersion(buildId, 50) -> ramp set to (deploymentName/buildId, 50)
deployment.UnsetRampingVersion() -> ramp set to (nil, 0%)
deployment.RampToUnversioned(50) -> set to (nil, 50%)
```


<!-- If this breaks the Server, please provide the Server PR to merge
right after this PR was merged. -->
**Server PR**

---------

Co-authored-by: Spencer Judge <[email protected]>
Co-authored-by: Shahab Tajik <[email protected]>

Author: 3 people

openapi/openapiv2.json

@@ -21,12 +21,11 @@ message WorkerDeploymentOptions {
     // Required. Worker Deployment name.
     string deployment_name = 1;
     // The Build ID of the worker. Required when `worker_versioning_mode==VERSIONED`, in which case,
-    // the worker will be part of a Deployment Version identified by "<deployment_name>.<build_id>".
+    // the worker will be part of a Deployment Version.
     string build_id = 2;
     // Required. Versioning Mode for this worker. Must be the same for all workers with the
     // same `deployment_name` and `build_id` combination, across all Task Queues.
-    // When `worker_versioning_mode==VERSIONED`, the worker will be part of a Deployment Version
-    // identified by "<deployment_name>.<build_id>".
+    // When `worker_versioning_mode==VERSIONED`, the worker will be part of a Deployment Version.
     temporal.api.enums.v1.WorkerVersioningMode worker_versioning_mode = 3;
 }
 
@@ -95,8 +94,11 @@ message DeploymentListInfo {
 // their first poller arrives to the server.
 // Experimental. Worker Deployments are experimental and might significantly change in the future.
 message WorkerDeploymentVersionInfo {
-    // The fully-qualified string representation of the version, in the form "<deployment_name>.<build_id>".
-    string version = 1;
+    // Deprecated. Use `deployment_version`.
+    string version = 1 [deprecated = true];
+
+    // Required.
+    WorkerDeploymentVersion deployment_version = 11;
     string deployment_name = 2;
     google.protobuf.Timestamp create_time = 3;
 
@@ -185,40 +187,60 @@ message WorkerDeploymentInfo {
     string last_modifier_identity = 5;
 
     message WorkerDeploymentVersionSummary {
-        // The fully-qualified string representation of the version, in the form "<deployment_name>.<build_id>".
-        string version = 1;
+        // Deprecated. Use `deployment_version`.
+        string version = 1 [deprecated = true];
+
+        // Required.
+        WorkerDeploymentVersion deployment_version = 4;
         google.protobuf.Timestamp create_time = 2;
         enums.v1.VersionDrainageStatus drainage_status = 3;
     }
 }
 
+// A Worker Deployment Version (Version, for short) represents a
+// version of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)
+// Version records are created in Temporal server automatically when their
+// first poller arrives to the server.
+// Experimental. Worker Deployment Versions are experimental and might significantly change in the future.
+message WorkerDeploymentVersion {
+    // A unique identifier for this Version within the Deployment it is a part of.
+    // Not necessarily unique within the namespace.
+    // The combination of `deployment_name` and `build_id` uniquely identifies this
+    // Version within the namespace, because Deployment names are unique within a namespace.
+    string build_id = 1;
+
+    // Identifies the Worker Deployment this Version is part of.
+    string deployment_name = 2;
+}
+
 message VersionMetadata {
     // Arbitrary key-values.
     map<string, temporal.api.common.v1.Payload> entries = 1;
 }
 
 message RoutingConfig {
-    // Always present. Specifies which Deployment Version should should receive new workflow
-    // executions and tasks of existing unversioned or AutoUpgrade workflows.
-    // Can be one of the following:
-    // - A Deployment Version identifier in the form "<deployment_name>.<build_id>".
-    // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those
-    //   with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
-    // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp
-    // is set (see `ramping_version`.)
-    string current_version = 1;
-    // When present, it means the traffic is being shifted from the Current Version to the Ramping
-    // Version.
-    // Must always be different from Current Version. Can be one of the following:
-    // - A Deployment Version identifier in the form "<deployment_name>.<build_id>".
-    // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those
-    //   with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
+    // Specifies which Deployment Version should receive new workflow executions and tasks of
+    // existing unversioned or AutoUpgrade workflows.
+    // Nil value means no Version in this Deployment (except Ramping Version, if present) receives traffic other than tasks of previously Pinned workflows. In absence of a Current Version, remaining traffic after any ramp (if set)  goes to unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.). 
+    // Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage
+    // is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`).
+    temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7;
+    // Deprecated. Use `current_deployment_version`.
+    string current_version = 1 [deprecated = true];
+
+    // When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version.
+    // Must always be different from `current_deployment_version` unless both are nil.
+    // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
     // Note that it is possible to ramp from one Version to another Version, or from unversioned
     // workers to a particular Version, or from a particular Version to unversioned workers.
-    string ramping_version = 2;
+    temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9;
+    // Deprecated. Use `ramping_deployment_version`.
+    string ramping_version = 2 [deprecated = true];
+
     // Percentage of tasks that are routed to the Ramping Version instead of the Current Version.
     // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but
     // not yet "promoted" to be the Current Version, likely due to pending validations.
+    // A 0% value means the Ramping Version is receiving no traffic.
     float ramping_version_percentage = 3;
     // Last time current version was changed.
     google.protobuf.Timestamp current_version_changed_time = 4;

openapi/openapiv3.yaml

@@ -125,7 +125,15 @@ message WorkflowExecutionStartedEventAttributes {
     // of starting on the Current Version of its Task Queue.
     // This is set only if the child workflow is starting on a Task Queue belonging to the same
     // Worker Deployment Version.
-    string parent_pinned_worker_deployment_version = 34;
+    // Deprecated. Use `parent_pinned_deployment_version`.
+    string parent_pinned_worker_deployment_version = 34 [deprecated = true];
+
+    // When present, it means this is a child workflow of a parent that is Pinned to this Worker
+    // Deployment Version. In this case, child workflow will start as Pinned to this Version instead
+    // of starting on the Current Version of its Task Queue.
+    // This is set only if the child workflow is starting on a Task Queue belonging to the same
+    // Worker Deployment Version.
+    temporal.api.deployment.v1.WorkerDeploymentVersion parent_pinned_deployment_version = 36;
 
     // Priority metadata
     temporal.api.common.v1.Priority priority = 35;
@@ -216,11 +224,11 @@ message WorkflowTaskStartedEventAttributes {
     int64 history_size_bytes = 5;
     // Version info of the worker to whom this task was dispatched.
     // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
-    temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
+    temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true];
     // Used by server internally to properly reapply build ID redirects to an execution
     // when rebuilding it from events.
     // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
-    int64 build_id_redirect_counter = 7;
+    int64 build_id_redirect_counter = 7 [deprecated = true];
 }
 
 message WorkflowTaskCompletedEventAttributes {
@@ -231,12 +239,13 @@ message WorkflowTaskCompletedEventAttributes {
     // Identity of the worker who completed this task
     string identity = 3;
     // Binary ID of the worker who completed this task
-    string binary_checksum = 4;
+    // Deprecated. Replaced with `deployment_version`.
+    string binary_checksum = 4 [deprecated = true];
     // Version info of the worker who processed this workflow task. If present, the `build_id` field
     // within is also used as `binary_checksum`, which may be omitted in that case (it may also be
     // populated to preserve compatibility).
-    // Deprecated. Use `deployment` and `versioning_behavior` instead.
-    temporal.api.common.v1.WorkerVersionStamp worker_version = 5;
+    // Deprecated. Use `deployment_version` and `versioning_behavior` instead.
+    temporal.api.common.v1.WorkerVersionStamp worker_version = 5 [deprecated = true];
     // Data the SDK wishes to record for itself, but server need not interpret, and does not
     // directly impact workflow state.
     temporal.api.sdk.v1.WorkflowTaskCompletedMetadata sdk_metadata = 6;
@@ -247,7 +256,7 @@ message WorkflowTaskCompletedEventAttributes {
     // The deployment that completed this task. May or may not be set for unversioned workers,
     // depending on whether a value is sent by the SDK. This value updates workflow execution's
     // `versioning_info.deployment`.
-    // Deprecated. Replaced with `worker_deployment_version`.
+    // Deprecated. Replaced with `deployment_version`.
     temporal.api.deployment.v1.Deployment deployment = 7 [deprecated = true];
     // Versioning behavior sent by the worker that completed this task for this particular workflow
     // execution. UNSPECIFIED means the task was completed by an unversioned worker. This value
@@ -256,11 +265,16 @@ message WorkflowTaskCompletedEventAttributes {
     // The Worker Deployment Version that completed this task. Must be set if `versioning_behavior`
     // is set. This value updates workflow execution's `versioning_info.version`.
     // Experimental. Worker Deployments are experimental and might significantly change in the future.
-    string worker_deployment_version = 9;
+    // Deprecated. Replaced with `deployment_version`.
+    string worker_deployment_version = 9 [deprecated = true];
     // The name of Worker Deployment that completed this task. Must be set if `versioning_behavior`
     // is set. This value updates workflow execution's `worker_deployment_name`.
     // Experimental. Worker Deployments are experimental and might significantly change in the future.
     string worker_deployment_name = 10;
+    // The Worker Deployment Version that completed this task. Must be set if `versioning_behavior`
+    // is set. This value updates workflow execution's `versioning_info.deployment_version`.
+    // Experimental. Worker Deployments are experimental and might significantly change in the future.
+    temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 11;
 }
 
 message WorkflowTaskTimedOutEventAttributes {
@@ -287,14 +301,14 @@ message WorkflowTaskFailedEventAttributes {
     string new_run_id = 7;
     // TODO: ?
     int64 fork_event_version = 8;
-    // DEPRECATED since 1.21 - use `worker_version` instead.
+    // DEPRECATED since 1.21 - This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
     // If a worker explicitly failed this task, its binary id
-    string binary_checksum = 9;
+    string binary_checksum = 9 [deprecated = true];
     // Version info of the worker who processed this workflow task. If present, the `build_id` field
     // within is also used as `binary_checksum`, which may be omitted in that case (it may also be
     // populated to preserve compatibility).
-    // Deprecated. Use the info inside the corresponding WorkflowTaskStartedEvent
-    temporal.api.common.v1.WorkerVersionStamp worker_version = 10;
+    // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
+    temporal.api.common.v1.WorkerVersionStamp worker_version = 10 [deprecated = true];
 }
 
 message ActivityTaskScheduledEventAttributes {
@@ -337,7 +351,8 @@ message ActivityTaskScheduledEventAttributes {
     temporal.api.common.v1.RetryPolicy retry_policy = 12;
     // If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise,
     // Assignment rules of the activity's Task Queue will be used to determine the Build ID.
-    bool use_workflow_build_id = 13;
+    // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
+    bool use_workflow_build_id = 13 [deprecated = true];
     // Priority metadata. If this message is not present, or any fields are not
     // present, they inherit the values from the workflow.
     temporal.api.common.v1.Priority priority = 14;
@@ -357,11 +372,11 @@ message ActivityTaskStartedEventAttributes {
     temporal.api.failure.v1.Failure last_failure = 5;
     // Version info of the worker to whom this task was dispatched.
     // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
-    temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
+    temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true];
     // Used by server internally to properly reapply build ID redirects to an execution
     // when rebuilding it from events.
     // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
-    int64 build_id_redirect_counter = 7;
+    int64 build_id_redirect_counter = 7 [deprecated = true];
 }
 
 message ActivityTaskCompletedEventAttributes {
@@ -374,8 +389,8 @@ message ActivityTaskCompletedEventAttributes {
     // id of the worker that completed this task
     string identity = 4;
     // Version info of the worker who processed this workflow task.
-    // Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent
-    temporal.api.common.v1.WorkerVersionStamp worker_version = 5;
+    // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
+    temporal.api.common.v1.WorkerVersionStamp worker_version = 5 [deprecated = true];
 }
 
 message ActivityTaskFailedEventAttributes {
@@ -389,8 +404,8 @@ message ActivityTaskFailedEventAttributes {
     string identity = 4;
     temporal.api.enums.v1.RetryState retry_state = 5;
     // Version info of the worker who processed this workflow task.
-    // Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent
-    temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
+    // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
+    temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true];
 }
 
 message ActivityTaskTimedOutEventAttributes {
@@ -424,8 +439,8 @@ message ActivityTaskCanceledEventAttributes {
     // id of the worker who canceled this activity
     string identity = 5;
     // Version info of the worker who processed this workflow task.
-    // Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent
-    temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
+    // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
+    temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true];;
 }
 
 message TimerStartedEventAttributes {

temporal/api/deployment/v1/message.proto

@@ -35,27 +35,28 @@ message TaskQueueMetadata {
 
 // Experimental. Worker Deployments are experimental and might significantly change in the future.
 message TaskQueueVersioningInfo {
-    // Always present. Specifies which Deployment Version should receive new workflow
-    // executions and tasks of existing unversioned or AutoUpgrade workflows.
-    // Can be one of the following:
-    // - A Deployment Version identifier in the form "<deployment_name>.<build_id>".
-    // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those
-    //   with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
-    // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp
-    // is set (see `ramping_version`.)
-    string current_version = 1;
-    // When present, it means the traffic is being shifted from the Current Version to the Ramping
-    // Version.
-    // Must always be different from `current_version`. Can be one of the following:
-    // - A Deployment Version identifier in the form "<deployment_name>.<build_id>".
-    // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those
-    //   with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
+    // Specifies which Deployment Version should receive new workflow executions and tasks of
+    // existing unversioned or AutoUpgrade workflows.
+    // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
+    // Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage
+    // is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`).
+    temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7;
+    // Deprecated. Use `current_deployment_version`.
+    string current_version = 1 [deprecated = true];
+
+    // When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version.
+    // Must always be different from `current_deployment_version` unless both are nil.
+    // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)
     // Note that it is possible to ramp from one Version to another Version, or from unversioned
     // workers to a particular Version, or from a particular Version to unversioned workers.
-    string ramping_version = 2;
+    temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9;
+    // Deprecated. Use `ramping_deployment_version`.
+    string ramping_version = 2 [deprecated = true];
+
     // Percentage of tasks that are routed to the Ramping Version instead of the Current Version.
     // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but
     // not yet "promoted" to be the Current Version, likely due to pending validations.
+    // A 0% value means the Ramping Version is receiving no traffic.
     float ramping_version_percentage = 3;
     // Last time versioning information of this Task Queue changed.
     google.protobuf.Timestamp update_time = 4;