From af602c92d3d8b432a07a3f1e1316cf53fbdb1b2b Mon Sep 17 00:00:00 2001 From: ShahabT Date: Wed, 9 Oct 2024 23:51:29 -0700 Subject: [PATCH 1/3] Versioning3 proto updates for data plane APIs --- openapi/openapiv2.json | 40 ++++++++++++++++-- openapi/openapiv3.yaml | 42 ++++++++++++++++++- temporal/api/common/v1/message.proto | 10 ++++- temporal/api/enums/v1/workflow.proto | 11 ++++- temporal/api/history/v1/message.proto | 4 ++ temporal/api/workflow/v1/message.proto | 12 ++++++ .../workflowservice/v1/request_response.proto | 9 ++++ 7 files changed, 120 insertions(+), 8 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 0bb18598..7c90958e 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11449,6 +11449,16 @@ }, "description": "VersionInfo contains details about current and recommended release versions as well as alerts and upgrade instructions." }, + "v1VersioningBehavior": { + "type": "string", + "enum": [ + "VERSIONING_BEHAVIOR_UNSPECIFIED", + "VERSIONING_BEHAVIOR_PINNED", + "VERSIONING_BEHAVIOR_AUTO_UPGRADE" + ], + "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", + "description": " - VERSIONING_BEHAVIOR_PINNED: Workflow should be pinned to the current build ID until manually moved.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow automatically moves to the latest version (default build ID of the task queue) when the next\ntask is dispatched." + }, "v1WaitPolicy": { "type": "object", "properties": { @@ -11469,9 +11479,13 @@ "useVersioning": { "type": "boolean", "description": "If set, the worker is opting in to worker versioning, and wishes to only receive appropriate\ntasks." + }, + "deploymentName": { + "type": "string", + "description": "Must be sent if user has set a deployment name (versioning-3)." } }, - "description": "Identifies the version(s) that a worker is compatible with when polling or identifying itself,\nand whether or not this worker is opting into the build-id based versioning feature. This is\nused by matching to determine which workers ought to receive what tasks." + "description": "Identifies the version that a worker is compatible with when polling or identifying itself,\nand whether or not this worker is opting into the build-id based versioning feature. This is\nused by matching to determine which workers ought to receive what tasks." }, "v1WorkerVersionStamp": { "type": "object", @@ -11483,9 +11497,13 @@ "useVersioning": { "type": "boolean", "description": "If set, the worker is opting in to worker versioning. Otherwise, this is used only as a\nmarker for workflow reset points and the BuildIDs search attribute." + }, + "deploymentName": { + "type": "string", + "description": "Must be sent if user has set a deployment name (versioning-3)." } }, - "title": "Identifies the version(s) of a worker that processed a task" + "title": "Identifies the version of a worker that received or processed a task" }, "v1WorkflowExecution": { "type": "object", @@ -11731,12 +11749,24 @@ }, "assignedBuildId": { "type": "string", - "description": "The currently assigned build ID for this execution. Presence of this value means worker versioning is used\nfor this execution. Assigned build ID is selected based on Worker Versioning Assignment Rules\nwhen the first workflow task of the execution is scheduled. If the first workflow task fails and is scheduled\nagain, the assigned build ID may change according to the latest versioning rules.\nAssigned build ID can also change in the middle of a execution if Compatible Redirect Rules are applied to\nthis execution." + "title": "The currently assigned build ID for this execution. Presence of this value means worker versioning is used\nfor this execution. Assigned build ID is selected based on Worker Versioning Assignment Rules\nwhen the first workflow task of the execution is scheduled. If the first workflow task fails and is scheduled\nagain, the assigned build ID may change according to the latest versioning rules.\nAssigned build ID can also change in the middle of a execution if Compatible Redirect Rules are applied to\nthis execution.\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" }, "inheritedBuildId": { "type": "string", "description": "Build ID inherited from a previous/parent execution. If present, assigned_build_id will be set to this, instead\nof using the assignment rules." }, + "buildId": { + "type": "string", + "title": "Current build ID of this workflow execution that determines the matching queue that new tasks of this execution\nwill be scheduled in. Current build ID is set after completion of the first workflow task, and\nwhen workflow moves to a different build ID either automatically or manually. (versioning-3)" + }, + "deploymentName": { + "type": "string", + "description": "The deployment name associated with this workflow's task queue + build ID. This is updated when `build_id` is\nupdated. `deployment_name` should be set if `build_id` field is set." + }, + "versioningBehavior": { + "$ref": "#/definitions/v1VersioningBehavior", + "description": "Determines how server should treat this execution when workers are upgraded. `versioning_behavior` has to be set\nif the `build_id` field is set." + }, "firstRunId": { "type": "string", "title": "The first run ID in the execution chain.\nExecutions created via the following operations are considered to be in the same chain\n- ContinueAsNew\n- Workflow Retry\n- Workflow Reset\n- Cron Schedule" @@ -12148,6 +12178,10 @@ "$ref": "#/definitions/v1WorkerVersionStamp", "title": "Version info of the worker who processed this workflow task. If present, the `build_id` field\nwithin is also used as `binary_checksum`, which may be omitted in that case (it may also be\npopulated to preserve compatibility).\nDeprecated. Use the info inside the corresponding WorkflowTaskStartedEvent" }, + "versioningBehavior": { + "$ref": "#/definitions/v1VersioningBehavior", + "description": "Versioning behavior sent by SDK for this workflow execution. Empty means behavior is not\nchanged in this event." + }, "sdkMetadata": { "$ref": "#/definitions/v1WorkflowTaskCompletedMetadata", "description": "Data the SDK wishes to record for itself, but server need not interpret, and does not\ndirectly impact workflow state." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index cd1ee0bb..fa8d52f6 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -8917,8 +8917,11 @@ components: description: |- If set, the worker is opting in to worker versioning, and wishes to only receive appropriate tasks. + deploymentName: + type: string + description: Must be sent if user has set a deployment name (versioning-3). description: |- - Identifies the version(s) that a worker is compatible with when polling or identifying itself, + Identifies the version 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. WorkerVersionStamp: @@ -8934,7 +8937,10 @@ components: description: |- 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. - description: Identifies the version(s) of a worker that processed a task + deploymentName: + type: string + description: Must be sent if user has set a deployment name (versioning-3). + description: Identifies the version of a worker that received or processed a task WorkflowEvent_EventReference: type: object properties: @@ -9234,11 +9240,33 @@ components: again, the assigned build ID may change according to the latest versioning rules. Assigned build ID can also change in the middle of a execution if Compatible Redirect Rules are applied to this execution. + Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] inheritedBuildId: type: string description: |- Build ID inherited from a previous/parent execution. If present, assigned_build_id will be set to this, instead of using the assignment rules. + buildId: + type: string + description: |- + Current build ID of this workflow execution that determines the matching queue that new tasks of this execution + will be scheduled in. Current build ID is set after completion of the first workflow task, and + when workflow moves to a different build ID either automatically or manually. (versioning-3) + deploymentName: + type: string + description: |- + The deployment name associated with this workflow's task queue + build ID. This is updated when `build_id` is + updated. `deployment_name` should be set if `build_id` field is set. + versioningBehavior: + enum: + - VERSIONING_BEHAVIOR_UNSPECIFIED + - VERSIONING_BEHAVIOR_PINNED + - VERSIONING_BEHAVIOR_AUTO_UPGRADE + type: string + description: |- + Determines how server should treat this execution when workers are upgraded. `versioning_behavior` has to be set + if the `build_id` field is set. + format: enum firstRunId: type: string description: |- @@ -9597,6 +9625,16 @@ components: 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 + versioningBehavior: + enum: + - VERSIONING_BEHAVIOR_UNSPECIFIED + - VERSIONING_BEHAVIOR_PINNED + - VERSIONING_BEHAVIOR_AUTO_UPGRADE + type: string + description: |- + Versioning behavior sent by SDK for this workflow execution. Empty means behavior is not + changed in this event. + format: enum sdkMetadata: allOf: - $ref: '#/components/schemas/WorkflowTaskCompletedMetadata' diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 13b82b14..48f5bc35 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -123,7 +123,7 @@ message MeteringMetadata { uint32 nonfirst_local_activity_execution_attempts = 13; } -// Identifies the version(s) of a worker that processed a task +// Identifies the version of a worker that received or processed a task message WorkerVersionStamp { // An opaque whole-worker identifier. Replaces the deprecated `binary_checksum` field when this // message is included in requests which previously used that. @@ -133,10 +133,13 @@ message WorkerVersionStamp { // marker for workflow reset points and the BuildIDs search attribute. bool use_versioning = 3; + // Must be sent if user has set a deployment name (versioning-3). + string deployment_name = 4; + // Later, may include bundle id that could be used for WASM and/or JS dynamically loadable bundles. } -// Identifies the version(s) that a worker is compatible with when polling or identifying itself, +// Identifies the version 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 { @@ -147,6 +150,9 @@ message WorkerVersionCapabilities { // tasks. bool use_versioning = 2; + // Must be sent if user has set a deployment name (versioning-3). + string deployment_name = 3; + // Later, may include info like "I can process WASM and/or JS bundles" } diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 54472099..4d8ca8cb 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -137,4 +137,13 @@ enum TimeoutType { TIMEOUT_TYPE_SCHEDULE_TO_START = 2; TIMEOUT_TYPE_SCHEDULE_TO_CLOSE = 3; TIMEOUT_TYPE_HEARTBEAT = 4; -} \ No newline at end of file +} + +enum VersioningBehavior { + VERSIONING_BEHAVIOR_UNSPECIFIED = 0; + // Workflow should be pinned to the current build ID until manually moved. + VERSIONING_BEHAVIOR_PINNED = 1; + // Workflow automatically moves to the latest version (default build ID of the task queue) when the next + // task is dispatched. + VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; +} diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 6e9a3ef8..5a5fc264 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -235,6 +235,10 @@ message WorkflowTaskCompletedEventAttributes { // populated to preserve compatibility). // Deprecated. Use the info inside the corresponding WorkflowTaskStartedEvent temporal.api.common.v1.WorkerVersionStamp worker_version = 5; + // Versioning behavior sent by SDK for this workflow execution. Empty means behavior is not + // changed in this event. + temporal.api.enums.v1.VersioningBehavior versioning_behavior = 7; + // 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; diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 467eb27e..60830bcf 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -87,10 +87,22 @@ message WorkflowExecutionInfo { // again, the assigned build ID may change according to the latest versioning rules. // Assigned build ID can also change in the middle of a execution if Compatible Redirect Rules are applied to // this execution. + // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] string assigned_build_id = 19; // Build ID inherited from a previous/parent execution. If present, assigned_build_id will be set to this, instead // of using the assignment rules. string inherited_build_id = 20; + // Current build ID of this workflow execution that determines the matching queue that new tasks of this execution + // will be scheduled in. Current build ID is set after completion of the first workflow task, and + // when workflow moves to a different build ID either automatically or manually. (versioning-3) + string build_id = 22; + // The deployment name associated with this workflow's task queue + build ID. This is updated when `build_id` is + // updated. `deployment_name` should be set if `build_id` field is set. + string deployment_name = 23; + // Determines how server should treat this execution when workers are upgraded. `versioning_behavior` has to be set + // if the `build_id` field is set. + temporal.api.enums.v1.VersioningBehavior versioning_behavior = 24; + // The first run ID in the execution chain. // Executions created via the following operations are considered to be in the same chain // - ContinueAsNew diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c9cc1cfc..0d1682ea 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -347,6 +347,15 @@ message RespondWorkflowTaskCompletedRequest { // 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; + // Versioning behavior explicitly specified by user for this workflow type. + // If absent, `default_versioning_behavior` will be used. + // At least one of `versioning_behavior` or `default_versioning_behavior` should be set when + // `worker_version_stamp.use_versioning` is `true` and `worker_version_stamp.deployment_name` is + // provided (which means versioning-3 API is used). + temporal.api.enums.v1.VersioningBehavior versioning_behavior = 14; + // Default versioning behavior that is set at worker server level. + temporal.api.enums.v1.VersioningBehavior default_versioning_behavior = 15; + // Default versioning behavior that is set at worker server level. // Protocol messages piggybacking on a WFT as a transport repeated temporal.api.protocol.v1.Message messages = 11; // Data the SDK wishes to record for itself, but server need not interpret, and does not From 8f96980c6ec279c7d7014c18458058d57645f228 Mon Sep 17 00:00:00 2001 From: ShahabT Date: Fri, 11 Oct 2024 10:07:48 -0700 Subject: [PATCH 2/3] address feedback --- temporal/api/history/v1/message.proto | 2 +- temporal/api/workflowservice/v1/request_response.proto | 9 ++------- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 5a5fc264..47c88eb6 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -235,7 +235,7 @@ message WorkflowTaskCompletedEventAttributes { // populated to preserve compatibility). // Deprecated. Use the info inside the corresponding WorkflowTaskStartedEvent temporal.api.common.v1.WorkerVersionStamp worker_version = 5; - // Versioning behavior sent by SDK for this workflow execution. Empty means behavior is not + // Versioning behavior sent by SDK for this workflow execution. Unspecified means behavior is not // changed in this event. temporal.api.enums.v1.VersioningBehavior versioning_behavior = 7; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 0d1682ea..0f04c9fa 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -347,15 +347,10 @@ message RespondWorkflowTaskCompletedRequest { // 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; - // Versioning behavior explicitly specified by user for this workflow type. - // If absent, `default_versioning_behavior` will be used. - // At least one of `versioning_behavior` or `default_versioning_behavior` should be set when - // `worker_version_stamp.use_versioning` is `true` and `worker_version_stamp.deployment_name` is - // provided (which means versioning-3 API is used). + // Must be set when versioning-3 is used (i.e. `worker_version_stamp.use_versioning` is `true` + // and `worker_version_stamp.deployment_name` is provided). temporal.api.enums.v1.VersioningBehavior versioning_behavior = 14; // Default versioning behavior that is set at worker server level. - temporal.api.enums.v1.VersioningBehavior default_versioning_behavior = 15; - // Default versioning behavior that is set at worker server level. // Protocol messages piggybacking on a WFT as a transport repeated temporal.api.protocol.v1.Message messages = 11; // Data the SDK wishes to record for itself, but server need not interpret, and does not From 351675e3799a2443ec20ca4e439ad05f7df935b6 Mon Sep 17 00:00:00 2001 From: ShahabT Date: Fri, 11 Oct 2024 13:05:21 -0700 Subject: [PATCH 3/3] gen files --- openapi/openapiv2.json | 2 +- openapi/openapiv3.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 7c90958e..33adc283 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -12180,7 +12180,7 @@ }, "versioningBehavior": { "$ref": "#/definitions/v1VersioningBehavior", - "description": "Versioning behavior sent by SDK for this workflow execution. Empty means behavior is not\nchanged in this event." + "description": "Versioning behavior sent by SDK for this workflow execution. Unspecified means behavior is not\nchanged in this event." }, "sdkMetadata": { "$ref": "#/definitions/v1WorkflowTaskCompletedMetadata", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index fa8d52f6..67220753 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -9632,7 +9632,7 @@ components: - VERSIONING_BEHAVIOR_AUTO_UPGRADE type: string description: |- - Versioning behavior sent by SDK for this workflow execution. Empty means behavior is not + Versioning behavior sent by SDK for this workflow execution. Unspecified means behavior is not changed in this event. format: enum sdkMetadata: