Skip to content

Commit

Permalink
Final versioning API changes (#285)
Browse files Browse the repository at this point in the history 
* Add versioning stamp to activity task completions

* Add to failed / cancelled events

* Change use latest flag to use compat

* Add use_versioning flag to capabilities message & comment wording updates
  • Loading branch information
@Sushisource
Sushisource committed May 25, 2023
1 parent c3d063b commit 572a6c5
Show file tree
Hide file tree
Showing 4 changed files with 74 additions and 54 deletions.
29 changes: 11 additions & 18 deletions temporal/api/command/v1/message.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,12 +83,10 @@ message ScheduleActivityTaskCommandAttributes {
// Request to start the activity directly bypassing matching service and worker polling
// The slot for executing the activity should be reserved when setting this field to true.
bool request_eager_execution = 12;
// If this is set and the workflow executing this command is on a task queue using build-id
// versioning, then the scheduled activity will not use the same compatible version set (which
// is the default behavior) and instead will use the current overall default for the queue.
// If this command's `task_queue` field differs from the executing workflow's task queue, then
// this flag has no effect.
bool use_latest_build_id = 13;
// If this is set, the workflow executing this command wishes to start the activity using
// a version compatible with the version that this workflow most recently ran on, if such
// behavior is possible.
bool use_compatible_version = 13;
}

message RequestCancelActivityTaskCommandAttributes {
Expand Down Expand Up @@ -197,12 +195,9 @@ message ContinueAsNewWorkflowExecutionCommandAttributes {
temporal.api.common.v1.Header header = 12;
temporal.api.common.v1.Memo memo = 13;
temporal.api.common.v1.SearchAttributes search_attributes = 14;
// If this is set and the workflow executing this command is on a task queue using build-id
// versioning, then the continued workflow will not use the same compatible version set (which
// is the default behavior) and instead will use the current overall default for the queue.
// If this command's `task_queue` field differs from the executing workflow's task queue, then
// this flag has no effect.
bool use_latest_build_id = 15;
// If this is set, the workflow executing this command wishes to continue as new using a version
// compatible with the version that this workflow most recently ran on.
bool use_compatible_version = 15;

// `workflow_execution_timeout` is omitted as it shouldn't be overridden from within a workflow.
}
Expand Down Expand Up @@ -230,12 +225,10 @@ message StartChildWorkflowExecutionCommandAttributes {
temporal.api.common.v1.Header header = 14;
temporal.api.common.v1.Memo memo = 15;
temporal.api.common.v1.SearchAttributes search_attributes = 16;
// If this is set and the workflow executing this command is on a task queue using build-id
// versioning, then the child workflow will not use the same compatible version set (which
// is the default behavior) and instead will use the current overall default for the queue.
// If this command's `task_queue` field differs from the executing workflow's task queue, then
// this flag has no effect.
bool use_latest_build_id = 17;
// If this is set, the workflow executing this command wishes to start the child workflow using
// a version compatible with the version that this workflow most recently ran on, if such
// behavior is possible.
bool use_compatible_version = 17;
}

message ProtocolMessageCommandAttributes {
Expand Down
15 changes: 11 additions & 4 deletions temporal/api/common/v1/message.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,21 +124,28 @@ message MeteringMetadata {

// Identifies the version(s) of a worker that processed a task
message WorkerVersionStamp {
// An opaque whole-worker identifier
// An opaque whole-worker identifier. Replaces the deprecated `binary_checksum` field when this
// message is included in requests which previously used that.
string build_id = 1;
// Set if the worker used a dynamically loadable bundle to process
// the task. The bundle could be a WASM blob, JS bundle, etc.
string bundle_id = 2;

// If set, the worker is opting in to worker versioning. Otherwise, this is used as a marker for workflow reset
// points and the BuildIDs search attribute.
// If set, the worker is opting in to worker versioning. Otherwise, this is used only as a
// marker for workflow reset points and the BuildIDs search attribute.
bool use_versioning = 3;
}

// Identifies the version(s) that a worker is compatible with when polling or identifying itself
// Identifies the version(s) that a worker is compatible with when polling or identifying itself,
// and whether or not this worker is opting into the build-id based versioning feature. This is
// used by matching to determine which workers ought to receive what tasks.
message WorkerVersionCapabilities {
// An opaque whole-worker identifier
string build_id = 1;

// If set, the worker is opting in to worker versioning, and wishes to only receive appropriate
// tasks.
bool use_versioning = 2;

// Later, may include info like "I can process WASM and/or JS bundles"
}
45 changes: 26 additions & 19 deletions temporal/api/history/v1/message.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,12 +160,9 @@ message WorkflowExecutionContinuedAsNewEventAttributes {
temporal.api.common.v1.Header header = 12;
temporal.api.common.v1.Memo memo = 13;
temporal.api.common.v1.SearchAttributes search_attributes = 14;
// If this is set and the workflow executing this command is on a task queue using build-id
// versioning, then the scheduled activity will not use the same compatible version set (which
// is the default behavior) and instead will use the current overall default for the queue.
// If this command's `task_queue` field differs from the executing workflow's task queue, then
// this flag has no effect.
bool use_latest_build_id = 15;
// If this is set, the workflow executing this command wishes to continue as new using a version
// compatible with the version that this workflow most recently ran on.
bool use_compatible_version = 15;

// workflow_execution_timeout is omitted as it shouldn't be overridden from within a workflow.
}
Expand Down Expand Up @@ -243,8 +240,13 @@ message WorkflowTaskFailedEventAttributes {
string new_run_id = 7;
// TODO: ?
int64 fork_event_version = 8;
// If a worker explicitly failed this task, it's binary id
// DEPRECATED since 1.21 - use `worker_version` instead.
// If a worker explicitly failed this task, its binary id
string binary_checksum = 9;
// Version info of the worker who processed this workflow task, or missing if worker is not
// using versioning. 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).
temporal.api.common.v1.WorkerVersionStamp worker_version = 10;
}

message ActivityTaskScheduledEventAttributes {
Expand Down Expand Up @@ -285,12 +287,10 @@ message ActivityTaskScheduledEventAttributes {
// configuration. Retries will happen up to `schedule_to_close_timeout`. To disable retries set
// retry_policy.maximum_attempts to 1.
temporal.api.common.v1.RetryPolicy retry_policy = 12;
// If this is set and the workflow executing this command is on a task queue using build-id
// versioning, then the scheduled activity will not use the same compatible version set (which
// is the default behavior) and instead will use the current overall default for the queue.
// If this command's `task_queue` field differs from the executing workflow's task queue, then
// this flag has no effect.
bool use_latest_build_id = 13;
// If this is set, the workflow executing this command wishes to start the activity using
// a version compatible with the version that this workflow most recently ran on, if such
// behavior is possible.
bool use_compatible_version = 13;
}

message ActivityTaskStartedEventAttributes {
Expand All @@ -316,6 +316,9 @@ message ActivityTaskCompletedEventAttributes {
int64 started_event_id = 3;
// id of the worker that completed this task
string identity = 4;
// Version info of the worker who processed this activity task, or missing if worker is not
// using versioning.
temporal.api.common.v1.WorkerVersionStamp worker_version = 5;
}

message ActivityTaskFailedEventAttributes {
Expand All @@ -328,6 +331,9 @@ message ActivityTaskFailedEventAttributes {
// id of the worker that failed this task
string identity = 4;
temporal.api.enums.v1.RetryState retry_state = 5;
// Version info of the worker who processed this activity task, or missing if worker is not
// using versioning.
temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
}

message ActivityTaskTimedOutEventAttributes {
Expand Down Expand Up @@ -360,6 +366,9 @@ message ActivityTaskCanceledEventAttributes {
int64 started_event_id = 4;
// id of the worker who canceled this activity
string identity = 5;
// Version info of the worker who processed this activity task, or missing if worker is not
// using versioning.
temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
}

message TimerStartedEventAttributes {
Expand Down Expand Up @@ -577,12 +586,10 @@ message StartChildWorkflowExecutionInitiatedEventAttributes {
temporal.api.common.v1.Header header = 15;
temporal.api.common.v1.Memo memo = 16;
temporal.api.common.v1.SearchAttributes search_attributes = 17;
// If this is set and the workflow executing this command is on a task queue using build-id
// versioning, then the child workflow will not use the same compatible version set (which
// is the default behavior) and instead will use the current overall default for the queue.
// If this command's `task_queue` field differs from the executing workflow's task queue, then
// this flag has no effect.
bool use_latest_build_id = 19;
// If this is set, the workflow executing this command wishes to start the child workflow using
// a version compatible with the version that this workflow most recently ran on, if such
// behavior is possible.
bool use_compatible_version = 19;
}

message StartChildWorkflowExecutionFailedEventAttributes {
Expand Down
39 changes: 26 additions & 13 deletions temporal/api/workflowservice/v1/request_response.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,14 +238,12 @@ message PollWorkflowTaskQueueRequest {
temporal.api.taskqueue.v1.TaskQueue task_queue = 2;
// The identity of the worker/client who is polling this task queue
string identity = 3;
// DEPRECATED since 1.21 - use `worker_version_capabilities` instead.
// Each worker process should provide an ID unique to the specific set of code it is running
// "checksum" in this field name isn't very accurate, it should be though of as an id.
string binary_checksum = 4;
// If set, the worker is opting in to versioning and wishes to only
// receive tasks that are considered compatible with the version capabilities provided.
// Doing so only makes sense in conjunction with the `UpdateWorkerBuildIdCompatibility` API.
// When this field has a `worker_build_id`, and `binary_checksum` is not
// set, that value should also be considered as the `binary_checksum`.
// Information about this worker's build identifier and if it is choosing to use the versioning
// feature. See the `WorkerVersionCapabilities` docstring for more.
temporal.api.common.v1.WorkerVersionCapabilities worker_version_capabilities = 5;
}

Expand Down Expand Up @@ -309,16 +307,15 @@ message RespondWorkflowTaskCompletedRequest {
// something useful, but cannot complete it within the workflow task timeout. Local activities
// which run for longer than the task timeout being the prime example.
bool force_create_new_workflow_task = 6;
// DEPRECATED since 1.21 - use `worker_version_stamp` instead.
// Worker process' unique binary id
string binary_checksum = 7;
// Responses to the `queries` field in the task being responded to
map<string, temporal.api.query.v1.WorkflowQueryResult> query_results = 8;
string namespace = 9;
// If using versioning, the worker uses this field to indicate what version(s) it used to
// process the task. When this field has a `worker_build_id`, and `binary_checksum` is not set,
// that value should also be considered as the `binary_checksum`. Leaving this field empty when
// replying to a task has had this field previously populated in history in an error, and such
// a completion will be rejected.
// Version info of the worker who processed this task. This message's `build_id` field should
// always be set by SDKs. Workers opting into versioning will also set the `use_versioning`
// field to true. See message docstrings for more.
temporal.api.common.v1.WorkerVersionStamp worker_version_stamp = 10;
// Protocol messages piggybacking on a WFT as a transport
repeated temporal.api.protocol.v1.Message messages = 11;
Expand Down Expand Up @@ -348,11 +345,16 @@ message RespondWorkflowTaskFailedRequest {
temporal.api.failure.v1.Failure failure = 3;
// The identity of the worker/client
string identity = 4;
// DEPRECATED since 1.21 - use `worker_version_stamp` instead.
// Worker process' unique binary id
string binary_checksum = 5;
string namespace = 6;
// Protocol messages piggybacking on a WFT as a transport
repeated temporal.api.protocol.v1.Message messages = 7;
// Version info of the worker who processed this task. This message's `build_id` field should
// always be set by SDKs. Workers opting into versioning will also set the `use_versioning`
// field to true. See message docstrings for more.
temporal.api.common.v1.WorkerVersionStamp worker_version = 8;
}

message RespondWorkflowTaskFailedResponse {
Expand All @@ -364,9 +366,8 @@ message PollActivityTaskQueueRequest {
// The identity of the worker/client
string identity = 3;
temporal.api.taskqueue.v1.TaskQueueMetadata task_queue_metadata = 4;
// If set, the worker is opting in to versioning and wishes to only
// receive tasks that are considered compatible with the capabilities provided.
// Doing so only makes sense in conjunction with the `UpdateWorkerBuildIdCompatibility` API.
// Information about this worker's build identifier and if it is choosing to use the versioning
// feature. See the `WorkerVersionCapabilities` docstring for more.
temporal.api.common.v1.WorkerVersionCapabilities worker_version_capabilities = 5;
}

Expand Down Expand Up @@ -463,6 +464,10 @@ message RespondActivityTaskCompletedRequest {
// The identity of the worker/client
string identity = 3;
string namespace = 4;
// Version info of the worker who processed this task. This message's `build_id` field should
// always be set by SDKs. Workers opting into versioning will also set the `use_versioning`
// field to true. See message docstrings for more.
temporal.api.common.v1.WorkerVersionStamp worker_version = 5;
}

message RespondActivityTaskCompletedResponse {
Expand Down Expand Up @@ -496,6 +501,10 @@ message RespondActivityTaskFailedRequest {
string namespace = 4;
// Additional details to be stored as last activity heartbeat
temporal.api.common.v1.Payloads last_heartbeat_details = 5;
// Version info of the worker who processed this task. This message's `build_id` field should
// always be set by SDKs. Workers opting into versioning will also set the `use_versioning`
// field to true. See message docstrings for more.
temporal.api.common.v1.WorkerVersionStamp worker_version = 6;
}

message RespondActivityTaskFailedResponse {
Expand Down Expand Up @@ -535,6 +544,10 @@ message RespondActivityTaskCanceledRequest {
// The identity of the worker/client
string identity = 3;
string namespace = 4;
// Version info of the worker who processed this task. This message's `build_id` field should
// always be set by SDKs. Workers opting into versioning will also set the `use_versioning`
// field to true. See message docstrings for more.
temporal.api.common.v1.WorkerVersionStamp worker_version = 5;
}

message RespondActivityTaskCanceledResponse {
Expand Down

0 comments on commit 572a6c5

Please sign in to comment.