Skip to content

Commit 33cbaa8

Browse files
ShahabTcarlydf
ShahabT
and
carlydf
authored
Versioning 3 Pre-Release APIs (#496)
<!-- Describe what has changed in this PR --> **What changed?** Includes: - Added `versioning_info` to `WorkflowExecutionInfo`, containing `VersioningBehavior`, current `Deployment`, `VersioningOverride`, and ongoing `DeploymentTransition` for an execution. - Added Deployment APIs, for managing worker deployments: - `DescribeDeployment` - `ListDeployments` - `GetCurrentDeployment` - `SetCurrentDeployment` (tentative) - `GetDeploymentReachability` - Added `UpdateWorkflowExecutionOptions` API (and its batch mode) so users can set versioning override for executions. - Updated data-path APIs so SDK can send `Deployment` and `VersioningBehavior` info in task completion responses and in polls. - Deprecated some fields and massages belonging to Versioning 1-2 pre-release. <!-- Tell your future self why have you made these changes --> **Why?** Versioning 3 brings improved experience compared to last iterations of this project. It adds two new concepts: VersioningBehavior and Deployment. More info can be found in the proto documentation. <!-- Are there any breaking changes on binary or code level? --> **Breaking changes** None. Versioning 1-2 pre-release APIs are still supported, until further notice. <!-- If this breaks the Server, please provide the Server PR to merge right after this PR was merged. --> **Server PR** temporalio/temporal#6890 --------- Co-authored-by: Carly de Frondeville <[email protected]>
1 parent 8ab82a6 commit 33cbaa8

File tree

12 files changed

+2423
-89
lines changed

12 files changed

+2423
-89
lines changed

‎openapi/openapiv2.json‎

Lines changed: 941 additions & 24 deletions
Large diffs are not rendered by default.

‎openapi/openapiv3.yaml‎

Lines changed: 981 additions & 46 deletions
Large diffs are not rendered by default.

‎temporal/api/batch/v1/message.proto‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,12 @@ option java_outer_classname = "MessageProto";
3131
option ruby_package = "Temporalio::Api::Batch::V1";
3232
option csharp_namespace = "Temporalio.Api.Batch.V1";
3333

34+
import "google/protobuf/field_mask.proto";
3435
import "google/protobuf/timestamp.proto";
35-
3636
import "temporal/api/common/v1/message.proto";
3737
import "temporal/api/enums/v1/batch_operation.proto";
3838
import "temporal/api/enums/v1/reset.proto";
39+
import "temporal/api/workflow/v1/message.proto";
3940

4041
message BatchOperationInfo {
4142
// Batch job ID
@@ -102,3 +103,17 @@ message BatchOperationReset {
102103
temporal.api.enums.v1.ResetReapplyType reset_reapply_type = 2;
103104

104105
}
106+
107+
// BatchOperationUpdateWorkflowExecutionOptions sends UpdateWorkflowExecutionOptions requests to batch workflows.
108+
// Keep the parameters in sync with temporal.api.workflowservice.v1.UpdateWorkflowExecutionOptionsRequest.
109+
message BatchOperationUpdateWorkflowExecutionOptions {
110+
// The identity of the worker/client.
111+
string identity = 1;
112+
113+
// Workflow Execution options. Partial updates are accepted and controlled by update_mask.
114+
temporal.api.workflow.v1.WorkflowExecutionOptions workflow_execution_options = 2;
115+
116+
// Controls which fields from `workflow_execution_options` will be applied.
117+
// To unset a field, set it to null and use the update mask to indicate that it should be mutated.
118+
google.protobuf.FieldMask update_mask = 3;
119+
}

‎temporal/api/common/v1/message.proto‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ message MeteringMetadata {
123123
uint32 nonfirst_local_activity_execution_attempts = 13;
124124
}
125125

126+
// Deprecated. This message is replaced with `Deployment` and `VersioningBehavior`.
126127
// Identifies the version(s) of a worker that processed a task
127128
message WorkerVersionStamp {
128129
// An opaque whole-worker identifier. Replaces the deprecated `binary_checksum` field when this
@@ -136,7 +137,7 @@ message WorkerVersionStamp {
136137
// Later, may include bundle id that could be used for WASM and/or JS dynamically loadable bundles.
137138
}
138139

139-
// Identifies the version(s) that a worker is compatible with when polling or identifying itself,
140+
// Identifies the version that a worker is compatible with when polling or identifying itself,
140141
// and whether or not this worker is opting into the build-id based versioning feature. This is
141142
// used by matching to determine which workers ought to receive what tasks.
142143
message WorkerVersionCapabilities {
@@ -147,6 +148,9 @@ message WorkerVersionCapabilities {
147148
// tasks.
148149
bool use_versioning = 2;
149150

151+
// Must be sent if user has set a deployment series name (versioning-3).
152+
string deployment_series_name = 4;
153+
150154
// Later, may include info like "I can process WASM and/or JS bundles"
151155
}
152156

‎temporal/api/deployment/v1/message.proto‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
// The MIT License
2+
//
3+
// Copyright (c) 2020 Temporal Technologies Inc. All rights reserved.
4+
//
5+
// Permission is hereby granted, free of charge, to any person obtaining a copy
6+
// of this software and associated documentation files (the "Software"), to deal
7+
// in the Software without restriction, including without limitation the rights
8+
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
// copies of the Software, and to permit persons to whom the Software is
10+
// furnished to do so, subject to the following conditions:
11+
//
12+
// The above copyright notice and this permission notice shall be included in
13+
// all copies or substantial portions of the Software.
14+
//
15+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
// THE SOFTWARE.
22+
23+
syntax = "proto3";
24+
25+
package temporal.api.deployment.v1;
26+
27+
option go_package = "go.temporal.io/api/deployment/v1;deployment";
28+
option java_package = "io.temporal.api.deployment.v1";
29+
option java_multiple_files = true;
30+
option java_outer_classname = "MessageProto";
31+
option ruby_package = "Temporalio::Api::Deployment::V1";
32+
option csharp_namespace = "Temporalio.Api.Deployment.V1";
33+
34+
import "google/protobuf/timestamp.proto";
35+
36+
import "temporal/api/enums/v1/task_queue.proto";
37+
import "temporal/api/common/v1/message.proto";
38+
39+
// `Deployment` identifies a deployment of Temporal workers. The combination of deployment series
40+
// name + build ID serves as the identifier. User can use `WorkerDeploymentOptions` in their worker
41+
// programs to specify these values.
42+
message Deployment {
43+
// Different versions of the same worker service/application are related together by having a
44+
// shared series name.
45+
// Out of all deployments of a series, one can be designated as the current deployment, which
46+
// receives new workflow executions and new tasks of workflows with
47+
// `VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.
48+
string series_name = 1;
49+
// Build ID changes with each version of the worker when the worker program code and/or config
50+
// changes.
51+
string build_id = 2;
52+
}
53+
54+
// `DeploymentInfo` holds information about a deployment. Deployment information is tracked
55+
// automatically by server as soon as the first poll from that deployment reaches the server. There
56+
// can be multiple task queue workers in a single deployment which are listed in this message.
57+
message DeploymentInfo {
58+
Deployment deployment = 1;
59+
google.protobuf.Timestamp create_time = 2;
60+
repeated TaskQueueInfo task_queue_infos = 3;
61+
// A user-defined set of key-values. Can be updated as part of write operations to the
62+
// deployment, such as `SetCurrentDeployment`.
63+
map<string, temporal.api.common.v1.Payload> metadata = 4;
64+
// If this deployment is the current deployment of its deployment series.
65+
bool is_current = 5;
66+
67+
message TaskQueueInfo {
68+
string name = 1;
69+
temporal.api.enums.v1.TaskQueueType type = 2;
70+
// When server saw the first poller for this task queue in this deployment.
71+
google.protobuf.Timestamp first_poller_time = 3;
72+
}
73+
}
74+
75+
// Used as part of Deployment write APIs to update metadata attached to a deployment.
76+
message UpdateDeploymentMetadata {
77+
map<string, temporal.api.common.v1.Payload> upsert_entries = 1;
78+
// List of keys to remove from the metadata.
79+
repeated string remove_entries = 2;
80+
}
81+
82+
// DeploymentListInfo is an abbreviated set of fields from DeploymentInfo that's returned in
83+
// ListDeployments.
84+
message DeploymentListInfo {
85+
deployment.v1.Deployment deployment = 1;
86+
google.protobuf.Timestamp create_time = 2;
87+
// If this deployment is the current deployment of its deployment series.
88+
bool is_current = 3;
89+
}

‎temporal/api/enums/v1/deployment.proto‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
// The MIT License
2+
//
3+
// Copyright (c) 2020 Temporal Technologies Inc. All rights reserved.
4+
//
5+
// Permission is hereby granted, free of charge, to any person obtaining a copy
6+
// of this software and associated documentation files (the "Software"), to deal
7+
// in the Software without restriction, including without limitation the rights
8+
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
// copies of the Software, and to permit persons to whom the Software is
10+
// furnished to do so, subject to the following conditions:
11+
//
12+
// The above copyright notice and this permission notice shall be included in
13+
// all copies or substantial portions of the Software.
14+
//
15+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
// THE SOFTWARE.
22+
23+
syntax = "proto3";
24+
25+
package temporal.api.enums.v1;
26+
27+
option go_package = "go.temporal.io/api/enums/v1;enums";
28+
option java_package = "io.temporal.api.enums.v1";
29+
option java_multiple_files = true;
30+
option java_outer_classname = "DeploymentProto";
31+
option ruby_package = "Temporalio::Api::Enums::V1";
32+
option csharp_namespace = "Temporalio.Api.Enums.V1";
33+
34+
// Specify the reachability level for a deployment so users can decide if it is time to
35+
// decommission the deployment.
36+
enum DeploymentReachability {
37+
// Reachability level is not specified.
38+
DEPLOYMENT_REACHABILITY_UNSPECIFIED = 0;
39+
// The deployment is reachable by new and/or open workflows. The deployment cannot be
40+
// decommissioned safely.
41+
DEPLOYMENT_REACHABILITY_REACHABLE = 1;
42+
// The deployment is not reachable by new or open workflows, but might be still needed by
43+
// Queries sent to closed workflows. The deployment can be decommissioned safely if user does
44+
// not query closed workflows.
45+
DEPLOYMENT_REACHABILITY_CLOSED_WORKFLOWS_ONLY = 2;
46+
// The deployment is not reachable by any workflow because all the workflows who needed this
47+
// deployment went out of retention period. The deployment can be decommissioned safely.
48+
DEPLOYMENT_REACHABILITY_UNREACHABLE = 3;
49+
}

‎temporal/api/enums/v1/event_type.proto‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,4 +185,6 @@ enum EventType {
185185
EVENT_TYPE_NEXUS_OPERATION_TIMED_OUT = 53;
186186
// A Nexus operation was requested to be canceled using a RequestCancelNexusOperation command.
187187
EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUESTED = 54;
188+
// Workflow execution options updated by user.
189+
EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED = 55;
188190
}

‎temporal/api/enums/v1/workflow.proto‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,4 +137,26 @@ enum TimeoutType {
137137
TIMEOUT_TYPE_SCHEDULE_TO_START = 2;
138138
TIMEOUT_TYPE_SCHEDULE_TO_CLOSE = 3;
139139
TIMEOUT_TYPE_HEARTBEAT = 4;
140-
}
140+
}
141+
142+
enum VersioningBehavior {
143+
// Workflow execution is unversioned. This is the legacy behavior. An unversioned workflow's
144+
// task may go to any unversioned worker who is polling for the task queue.
145+
VERSIONING_BEHAVIOR_UNSPECIFIED = 0;
146+
// Workflow will be pinned to the current deployment until completion. Can be overridden
147+
// explicitly via `UpdateWorkflowExecutionOptions` API.
148+
// Activities of `PINNED` workflows are sent to the same deployment. Exception to this would be
149+
// when the activity task queue workers are not present in the workflows deployment, in which
150+
// case the activity will be sent to the current deployment of its own task queue.
151+
VERSIONING_BEHAVIOR_PINNED = 1;
152+
// Workflow will automatically move to the current deployment of its task queue when the next
153+
// workflow task is dispatched.
154+
// Activities of `AUTO_UPGRADE` workflows are sent to the current deployment of the workflow
155+
// execution based on the last completed workflow task. Exception to this would be when the
156+
// activity task queue workers are not present in the workflow's deployment, in which case the
157+
// activity will be sent to the current deployment of its own task queue.
158+
// Workflows stuck on a backlogged activity will still auto-upgrade if the default deployment
159+
// of their task queue changes, without having to wait for the backlogged activity to complete
160+
// on the old deployment.
161+
VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2;
162+
}

‎temporal/api/history/v1/message.proto‎

Lines changed: 31 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ import "temporal/api/enums/v1/failed_cause.proto";
3939
import "temporal/api/enums/v1/update.proto";
4040
import "temporal/api/enums/v1/workflow.proto";
4141
import "temporal/api/common/v1/message.proto";
42+
import "temporal/api/deployment/v1/message.proto";
4243
import "temporal/api/failure/v1/message.proto";
4344
import "temporal/api/taskqueue/v1/message.proto";
4445
import "temporal/api/update/v1/message.proto";
@@ -104,7 +105,7 @@ message WorkflowExecutionStartedEventAttributes {
104105
string workflow_id = 28;
105106
// If this workflow intends to use anything other than the current overall default version for
106107
// the queue, then we include it here.
107-
// Deprecated. use `inherited_build_id` instead
108+
// Deprecated. [cleanup-experimental-wv]
108109
temporal.api.common.v1.WorkerVersionStamp source_version_stamp = 29;
109110
// Completion callbacks attached when this workflow was started.
110111
repeated temporal.api.common.v1.Callback completion_callbacks = 30;
@@ -128,7 +129,10 @@ message WorkflowExecutionStartedEventAttributes {
128129
// - The root workflow of W1 is W1 and the root workflow of W2 is W2.
129130
temporal.api.common.v1.WorkflowExecution root_workflow_execution = 31;
130131
// When present, this execution is assigned to the build ID of its parent or previous execution.
132+
// Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
131133
string inherited_build_id = 32;
134+
// Versioning override applied to this workflow when it was started.
135+
temporal.api.workflow.v1.VersioningOverride versioning_override = 33;
132136
}
133137

134138
message WorkflowExecutionCompletedEventAttributes {
@@ -215,9 +219,11 @@ message WorkflowTaskStartedEventAttributes {
215219
// just the event id of this event, so we don't include it explicitly here.
216220
int64 history_size_bytes = 5;
217221
// Version info of the worker to whom this task was dispatched.
222+
// Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
218223
temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
219224
// Used by server internally to properly reapply build ID redirects to an execution
220225
// when rebuilding it from events.
226+
// Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
221227
int64 build_id_redirect_counter = 7;
222228
}
223229

@@ -233,14 +239,23 @@ message WorkflowTaskCompletedEventAttributes {
233239
// Version info of the worker who processed this workflow task. If present, the `build_id` field
234240
// within is also used as `binary_checksum`, which may be omitted in that case (it may also be
235241
// populated to preserve compatibility).
236-
// Deprecated. Use the info inside the corresponding WorkflowTaskStartedEvent
242+
// Deprecated. Use `deployment` and `versioning_behavior` instead.
237243
temporal.api.common.v1.WorkerVersionStamp worker_version = 5;
238244
// Data the SDK wishes to record for itself, but server need not interpret, and does not
239245
// directly impact workflow state.
240246
temporal.api.sdk.v1.WorkflowTaskCompletedMetadata sdk_metadata = 6;
241247

242248
// Local usage data sent during workflow task completion and recorded here for posterity
243249
temporal.api.common.v1.MeteringMetadata metering_metadata = 13;
250+
251+
// The deployment that completed this task. May or may not be set for unversioned workers,
252+
// depending on whether a value is sent by the SDK. This value updates workflow execution's
253+
// `versioning_info.deployment`.
254+
temporal.api.deployment.v1.Deployment deployment = 7;
255+
// Versioning behavior sent by the worker that completed this task for this particular workflow
256+
// execution. UNSPECIFIED means the task was completed by an unversioned worker. This value
257+
// updates workflow execution's `versioning_info.behavior`.
258+
temporal.api.enums.v1.VersioningBehavior versioning_behavior = 8;
244259
}
245260

246261
message WorkflowTaskTimedOutEventAttributes {
@@ -333,9 +348,11 @@ message ActivityTaskStartedEventAttributes {
333348
// been retried.
334349
temporal.api.failure.v1.Failure last_failure = 5;
335350
// Version info of the worker to whom this task was dispatched.
351+
// Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
336352
temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
337353
// Used by server internally to properly reapply build ID redirects to an execution
338354
// when rebuilding it from events.
355+
// Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]
339356
int64 build_id_redirect_counter = 7;
340357
}
341358

@@ -723,19 +740,22 @@ message ChildWorkflowExecutionTerminatedEventAttributes {
723740
int64 started_event_id = 5;
724741
}
725742

743+
message WorkflowExecutionOptionsUpdatedEventAttributes {
744+
// Versioning override in the mutable state after event has been applied.
745+
temporal.api.workflow.v1.VersioningOverride versioning_override = 1;
746+
}
747+
748+
// Not used anywhere. Use case is replaced by WorkflowExecutionOptionsUpdatedEventAttributes
726749
message WorkflowPropertiesModifiedExternallyEventAttributes {
727-
// If set to a nonempty string, future workflow tasks for this workflow shall be dispatched on
728-
// the provided queue.
750+
// Not used.
729751
string new_task_queue = 1;
730-
// If set, update the workflow task timeout to this value.
752+
// Not used.
731753
google.protobuf.Duration new_workflow_task_timeout = 2;
732-
// If set, update the workflow run timeout to this value. May be set to 0 for no timeout.
754+
// Not used.
733755
google.protobuf.Duration new_workflow_run_timeout = 3;
734-
// If set, update the workflow execution timeout to this value. May be set to 0 for no timeout.
756+
// Not used.
735757
google.protobuf.Duration new_workflow_execution_timeout = 4;
736-
// If set, update the workflow memo with the provided values. The values will be merged with
737-
// the existing memo. If the user wants to delete values, a default/empty Payload should be
738-
// used as the value for the key being deleted.
758+
// Not used.
739759
temporal.api.common.v1.Memo upserted_memo = 5;
740760
}
741761

@@ -980,6 +1000,7 @@ message HistoryEvent {
9801000
NexusOperationCanceledEventAttributes nexus_operation_canceled_event_attributes = 57;
9811001
NexusOperationTimedOutEventAttributes nexus_operation_timed_out_event_attributes = 58;
9821002
NexusOperationCancelRequestedEventAttributes nexus_operation_cancel_requested_event_attributes = 59;
1003+
WorkflowExecutionOptionsUpdatedEventAttributes workflow_execution_options_updated_event_attributes = 60;
9831004
}
9841005
}
9851006

0 commit comments

Comments
 (0)