From 572a6c5cc5b865ab1a2f894b74835b5213540d7d Mon Sep 17 00:00:00 2001 From: Spencer Judge Date: Tue, 23 May 2023 16:30:42 -0700 Subject: [PATCH] Final versioning API changes (#285) * 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 --- temporal/api/command/v1/message.proto | 29 +++++------- temporal/api/common/v1/message.proto | 15 +++++-- temporal/api/history/v1/message.proto | 45 +++++++++++-------- .../workflowservice/v1/request_response.proto | 39 ++++++++++------ 4 files changed, 74 insertions(+), 54 deletions(-) diff --git a/temporal/api/command/v1/message.proto b/temporal/api/command/v1/message.proto index 34fe8fe1..8a2b2b6a 100644 --- a/temporal/api/command/v1/message.proto +++ b/temporal/api/command/v1/message.proto @@ -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 { @@ -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. } @@ -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 { diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index e7766ff2..a66e4d6a 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -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" } diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 0bd7974a..d515add7 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -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. } @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index b086b0fd..f148edb3 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -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; } @@ -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 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; @@ -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 { @@ -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; } @@ -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 { @@ -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 { @@ -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 {