diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 3f90a6a7..d8312bd3 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7868,6 +7868,18 @@ }, "description": "Replaces the routing rule with the given source Build ID." }, + "VersioningOverrideNonPinningPolicy": { + "type": "string", + "enum": [ + "NON_PINNING_POLICY_UNSPECIFIED", + "NON_PINNING_POLICY_REJECT", + "NON_PINNING_POLICY_IGNORE", + "NON_PINNING_POLICY_PINNED", + "NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW" + ], + "default": "NON_PINNING_POLICY_UNSPECIFIED", + "description": "Describes how a Pinning behavior override that keeps original pinning behavior\nshould be applied to workflows that do not have a pinning behavior.\nThis applies to all workflows that have not yet completed their first workflow\ntask, because only after first-workflow-task-completion does the server know the\nbehavior of a workflow execution.\n\n - NON_PINNING_POLICY_UNSPECIFIED: Unspecified.\n - NON_PINNING_POLICY_REJECT: Reject the override at apply time.\n - NON_PINNING_POLICY_IGNORE: Accept the override at apply time, but ignore it for workflows that do not\nhave a pinning behavior. Once a workflow's behavior is known, the override\nwill only affect it if that behavior is a pinning behavior.\n - NON_PINNING_POLICY_PINNED: Use Pinned.\n - NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW: Use PinnedUntilContinueAsNew." + }, "VersioningOverridePinnedOverride": { "type": "object", "properties": { @@ -7877,18 +7889,26 @@ }, "version": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "Required." + "description": "Required if the target workflow is not already pinned to a version.\n\nIf the target workflow is already using a pinning behavior and this field is omitted,\nthe effective pinned version will be the existing pinned version.\n\nIf the target workflow is not using a pinning behavior and this field is omitted,\nthe override request will be rejected." + }, + "ifNotPinning": { + "$ref": "#/definitions/VersioningOverrideNonPinningPolicy", + "description": "Required if behavior is PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING.\nIgnored if behavior is not PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING.\nWe will reject overrides that have PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING PinnedOverrideBehavior\nand UNSPECIFIED NonPinningPolicy before the batch even starts, but if it somehow sneaks in,\nUNSPECIFIED will be treated the same as REJECT." } - } + }, + "description": "Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to." }, "VersioningOverridePinnedOverrideBehavior": { "type": "string", "enum": [ "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "PINNED_OVERRIDE_BEHAVIOR_PINNED" + "PINNED_OVERRIDE_BEHAVIOR_PINNED", + "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW", + "PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING" ], "default": "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "description": "Used to specify different sub-types of Pinned override that we plan to add in the future.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Override workflow behavior to be Pinned." + "description": "`PinnedOverrideBehavior` controls how the override interacts with existing pinning\nbehaviors and with workflows that are not currently pinned.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Force the workflow to use the PINNED pinning behavior, regardless of its current\nversioning behavior.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Force the workflow to use the PINNED_UNTIL_CONTINUE_AS_NEW pinning behavior,\nregardless of its current versioning behavior.\n - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING: If the workflow is already using a pinning behavior (PINNED or\nPINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior.\nUse if_not_pinning to specify how to treat other workflows.", + "title": "\"Pinning behaviors\" refers to behaviors in which a workflow is explicitly assigned\nto a particular version. Currently, the pinning behaviors are:\n - PINNED\n - PINNED_UNTIL_CONTINUE_AS_NEW" }, "WorkerConfigAutoscalingPollerBehavior": { "type": "object", @@ -15477,6 +15497,18 @@ }, "description": "StructuredCalendarSpec describes an event specification relative to the\ncalendar, in a form that's easy to work with programmatically. Each field can\nbe one or more ranges.\nA timestamp matches if at least one range of each field matches the\ncorresponding fields of the timestamp, except for year: if year is missing,\nthat means all years match. For all fields besides year, at least one Range\nmust be present to match anything.\nRelative expressions such as \"last day of the month\" or \"third Monday\" are not currently\nrepresentable; callers must enumerate the concrete days they require." }, + "v1SuggestContinueAsNewReason": { + "type": "string", + "enum": [ + "SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED", + "SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE", + "SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS", + "SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES", + "SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED" + ], + "default": "SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED", + "description": "SuggestContinueAsNewReason specifies why SuggestContinueAsNew is true.\n\n - SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE: Workflow History size is getting too large.\n - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS: Workflow History event count is getting too large.\n - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES: Workflow's count of completed plus in-flight updates is too large.\n - SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED: Workflow's Target Worker Deployment Version is different from its\nPinned Version and the workflow's Versioning Behavior is PinnedUntilContinueAsNew." + }, "v1TaskIdBlock": { "type": "object", "properties": { @@ -16212,21 +16244,22 @@ "enum": [ "VERSIONING_BEHAVIOR_UNSPECIFIED", "VERSIONING_BEHAVIOR_PINNED", - "VERSIONING_BEHAVIOR_AUTO_UPGRADE" + "VERSIONING_BEHAVIOR_AUTO_UPGRADE", + "VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on the Current Deployment Version of its Task Queue, and then\nwill be pinned to that same Deployment Version until completion (the Version that\nthis Workflow is pinned to is specified in `versioning_info.version`).\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to the Current Deployment Version of its Task Queue when the\nnext workflow task is dispatched.\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current Deployment Version of its own task\nqueue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if the Current Deployment\nVersion of their Task Queue changes, without having to wait for the backlogged activity to\ncomplete on the old Version." + "description": "Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment\nVersions. The Versioning Behavior of a workflow execution is typically specified by the worker\nwho completes the first task of the execution, but is also overridable manually for new and\nexisting workflows (see VersioningOverride).\nExperimental. Worker Deployments are experimental and might significantly change in the future.\n\n - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the\nlegacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see\n`WorkerVersioningMode`.)\nUser needs to use Patching to keep the new code compatible with prior versions when dealing\nwith Unversioned workflows.\n - VERSIONING_BEHAVIOR_PINNED: Workflow will start on its Target Version and then will be pinned to that same Deployment\nVersion until completion (the Version that this Workflow is pinned to is specified in\n`versioning_info.version` and is the Pinned Version of the Workflow).\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on its Workflow ID and and the Ramp Percentage.\n\nThis behavior eliminates most of compatibility concerns users face when changing their code.\nPatching is not needed when pinned workflows code change.\nCan be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the\nexecution to another Deployment Version.\nActivities of `PINNED` workflows are sent to the same Deployment Version. Exception to this\nwould be when the activity Task Queue workers are not present in the workflow's Deployment\nVersion, in which case the activity will be sent to the Current Deployment Version of its own\ntask queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow will automatically move to its Target Version when the next workflow task is dispatched.\n\nThe workflow's Target Version is the Current Version of its Task Queue, or, if the\nTask Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target\nVersion has a P% chance of being the Ramping Version. Whether a workflow falls into the\nRamping group depends on its Workflow ID and and the Ramp Percentage.\n\nAutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the\nlatest Deployment Version, but the user still needs to use Patching to keep the new code\ncompatible with prior versions for changed workflow types.\nActivities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow\nexecution (as specified in versioning_info.version based on the last completed\nworkflow task). Exception to this would be when the activity Task Queue workers are not\npresent in the workflow's Deployment Version, in which case, the activity will be sent to a\ndifferent Deployment Version according to the Current or Ramping Deployment Version of its own\nTask Queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if their Target Version\nchanges, without having to wait for the backlogged activity to complete on the old Version.\n - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: The same semantics as PINNED, with the exception of Continue-As-New.\nWhen a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution\nwill start on the workflow's Target Version, with AUTO_UPGRADE behavior.\nOn the first workflow task completion of the new run, the workflow will assume\nthe behavior specified for that workflow type on the Target Version. If that\nbehavior is also PINNED_UNTIL_CONTINUE_AS_NEW, the new run will now be pinned to\nthat version until the next time it continues-as-new.\n\nWhen the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different\nfrom its Pinned Version, the workflow's continue_as_new_suggested flag will be true,\nso that these workflows can tell when continuing-as-new would cause a version change." }, "v1VersioningOverride": { "type": "object", "properties": { "pinned": { "$ref": "#/definitions/VersioningOverridePinnedOverride", - "description": "Send the next workflow task to the Version specified in the override." + "description": "Override the workflow to use a pinning behavior, optionally specifying a pinned\ndeployment version." }, "autoUpgrade": { "type": "boolean", - "description": "Send the next workflow task to the Current Deployment Version\nof its Task Queue when the next workflow task is dispatched." + "description": "Override the workflow to use AutoUpgrade. The next workflow task will be sent\nto the current deployment version of the workflow's task queue." }, "behavior": { "$ref": "#/definitions/v1VersioningBehavior", @@ -16241,7 +16274,7 @@ "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `override.pinned.version`." } }, - "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, takes precedence over the worker-sent values. See\n`WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call\n`UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask`\nto indicate that it should be mutated.\nPinned overrides are automatically inherited by child workflows, continue-as-new workflows,\nworkflow retries, and cron workflows." + "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, this override takes precedence over worker-sent values.\nSee `WorkflowExecutionInfo.VersioningInfo` for more information.\n\nTo remove the override, call `UpdateWorkflowExecutionOptions` with a null\n`VersioningOverride`, and use the `update_mask` to indicate that it should be mutated.\n\nPinning behavior overrides (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited\nby child workflows, workflow retries, and cron workflows.\n\nFor continue-as-new:\n - PINNED overrides are inherited by the new run.\n - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new,\n versioning behavior falls back to worker-sent values." }, "v1WaitPolicy": { "type": "object", @@ -17808,7 +17841,14 @@ }, "suggestContinueAsNew": { "type": "boolean", - "description": "True if this workflow should continue-as-new soon because its history size (in\neither event count or bytes) is getting large." + "title": "True if this workflow should continue-as-new soon. Reasons for this could be:\n - History size (in either event count or bytes) is getting large\n - Total number of completed and in-flight updates on the workflow is too large\n - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew" + }, + "suggestContinueAsNewReasons": { + "type": "array", + "items": { + "$ref": "#/definitions/v1SuggestContinueAsNewReason" + }, + "description": "The reason(s) that suggest_continue_as_new is true, if it is.\nNil if suggest_continue_as_new is false." }, "historySizeBytes": { "type": "string", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 9f3b310e..7c7b6ccf 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -13432,17 +13432,20 @@ components: pinned: allOf: - $ref: '#/components/schemas/VersioningOverride_PinnedOverride' - description: Send the next workflow task to the Version specified in the override. + description: |- + Override the workflow to use a pinning behavior, optionally specifying a pinned + deployment version. autoUpgrade: type: boolean description: |- - Send the next workflow task to the Current Deployment Version - of its Task Queue when the next workflow task is dispatched. + Override the workflow to use AutoUpgrade. The next workflow task will be sent + to the current deployment version of the workflow's task queue. behavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED - VERSIONING_BEHAVIOR_PINNED - VERSIONING_BEHAVIOR_AUTO_UPGRADE + - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW type: string description: |- Required. @@ -13464,12 +13467,19 @@ components: Deprecated. Use `override.pinned.version`. description: |- Used to override the versioning behavior (and pinned deployment version, if applicable) of a - specific workflow execution. If set, takes precedence over the worker-sent values. See - `WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call - `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` - to indicate that it should be mutated. - Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, - workflow retries, and cron workflows. + specific workflow execution. If set, this override takes precedence over worker-sent values. + See `WorkflowExecutionInfo.VersioningInfo` for more information. + + To remove the override, call `UpdateWorkflowExecutionOptions` with a null + `VersioningOverride`, and use the `update_mask` to indicate that it should be mutated. + + Pinning behavior overrides (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited + by child workflows, workflow retries, and cron workflows. + + For continue-as-new: + - PINNED overrides are inherited by the new run. + - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new, + versioning behavior falls back to worker-sent values. VersioningOverride_PinnedOverride: type: object properties: @@ -13477,6 +13487,8 @@ components: enum: - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED - PINNED_OVERRIDE_BEHAVIOR_PINNED + - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW + - PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING type: string description: |- Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. @@ -13485,7 +13497,30 @@ components: version: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: Required. + description: |- + Required if the target workflow is not already pinned to a version. + + If the target workflow is already using a pinning behavior and this field is omitted, + the effective pinned version will be the existing pinned version. + + If the target workflow is not using a pinning behavior and this field is omitted, + the override request will be rejected. + ifNotPinning: + enum: + - NON_PINNING_POLICY_UNSPECIFIED + - NON_PINNING_POLICY_REJECT + - NON_PINNING_POLICY_IGNORE + - NON_PINNING_POLICY_PINNED + - NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW + type: string + description: |- + Required if behavior is PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + Ignored if behavior is not PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + We will reject overrides that have PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING PinnedOverrideBehavior + and UNSPECIFIED NonPinningPolicy before the batch even starts, but if it somehow sneaks in, + UNSPECIFIED will be treated the same as REJECT. + format: enum + description: Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to. WaitPolicy: type: object properties: @@ -14913,6 +14948,7 @@ components: - VERSIONING_BEHAVIOR_UNSPECIFIED - VERSIONING_BEHAVIOR_PINNED - VERSIONING_BEHAVIOR_AUTO_UPGRADE + - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW type: string description: "Versioning behavior determines how the server should treat this execution when workers are\n upgraded. When present it means this workflow execution is versioned; UNSPECIFIED means\n unversioned. See the comments in `VersioningBehavior` enum for more info about different\n behaviors.\n\n Child workflows or CaN executions **inherit** their parent/previous run's effective Versioning \n Behavior and Version (except when the new execution runs on a task queue not belonging to the \n same deployment version as the parent/previous run's task queue). The first workflow task will\n be dispatched according to the inherited behavior (or to the current version of the task-queue's \n deployment in the case of AutoUpgrade.) After completion of their first workflow task the \n Deployment Version and Behavior of the execution will update according to configuration on the worker.\n \n Note that `behavior` is overridden by `versioning_override` if the latter is present." format: enum @@ -15186,6 +15222,7 @@ components: - VERSIONING_BEHAVIOR_UNSPECIFIED - VERSIONING_BEHAVIOR_PINNED - VERSIONING_BEHAVIOR_AUTO_UPGRADE + - VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW type: string description: |- Versioning behavior sent by the worker that completed this task for this particular workflow @@ -15390,8 +15427,24 @@ components: suggestContinueAsNew: type: boolean description: |- - True if this workflow should continue-as-new soon because its history size (in - either event count or bytes) is getting large. + True if this workflow should continue-as-new soon. Reasons for this could be: + - History size (in either event count or bytes) is getting large + - Total number of completed and in-flight updates on the workflow is too large + - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew + suggestContinueAsNewReasons: + type: array + items: + enum: + - SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED + - SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE + - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS + - SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES + - SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED + type: string + format: enum + description: |- + The reason(s) that suggest_continue_as_new is true, if it is. + Nil if suggest_continue_as_new is false. historySizeBytes: type: string description: |- diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 5e6ca6e3..1e18701b 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -134,9 +134,15 @@ enum VersioningBehavior { // User needs to use Patching to keep the new code compatible with prior versions when dealing // with Unversioned workflows. VERSIONING_BEHAVIOR_UNSPECIFIED = 0; - // Workflow will start on the Current Deployment Version of its Task Queue, and then - // will be pinned to that same Deployment Version until completion (the Version that - // this Workflow is pinned to is specified in `versioning_info.version`). + // Workflow will start on its Target Version and then will be pinned to that same Deployment + // Version until completion (the Version that this Workflow is pinned to is specified in + // `versioning_info.version` and is the Pinned Version of the Workflow). + // + // The workflow's Target Version is the Current Version of its Task Queue, or, if the + // Task Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target + // Version has a P% chance of being the Ramping Version. Whether a workflow falls into the + // Ramping group depends on its Workflow ID and and the Ramp Percentage. + // // This behavior eliminates most of compatibility concerns users face when changing their code. // Patching is not needed when pinned workflows code change. // Can be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the @@ -146,8 +152,13 @@ enum VersioningBehavior { // Version, in which case the activity will be sent to the Current Deployment Version of its own // task queue. VERSIONING_BEHAVIOR_PINNED = 1; - // Workflow will automatically move to the Current Deployment Version of its Task Queue when the - // next workflow task is dispatched. + // Workflow will automatically move to its Target Version when the next workflow task is dispatched. + // + // The workflow's Target Version is the Current Version of its Task Queue, or, if the + // Task Queue has a Ramping Version with non-zero Ramp Percentage `P`, the workflow's Target + // Version has a P% chance of being the Ramping Version. Whether a workflow falls into the + // Ramping group depends on its Workflow ID and and the Ramp Percentage. + // // AutoUpgrade behavior is suitable for long-running workflows as it allows them to move to the // latest Deployment Version, but the user still needs to use Patching to keep the new code // compatible with prior versions for changed workflow types. @@ -155,10 +166,39 @@ enum VersioningBehavior { // execution (as specified in versioning_info.version based on the last completed // workflow task). Exception to this would be when the activity Task Queue workers are not // present in the workflow's Deployment Version, in which case, the activity will be sent to a - // different Deployment Version according to the Current Deployment Version of its own task - // queue. - // Workflows stuck on a backlogged activity will still auto-upgrade if the Current Deployment - // Version of their Task Queue changes, without having to wait for the backlogged activity to - // complete on the old Version. + // different Deployment Version according to the Current or Ramping Deployment Version of its own + // Task Queue. + // Workflows stuck on a backlogged activity will still auto-upgrade if their Target Version + // changes, without having to wait for the backlogged activity to complete on the old Version. VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; + // The same semantics as PINNED, with the exception of Continue-As-New. + // When a PINNED_UNTIL_CONTINUE_AS_NEW workflow continues-as-new, the new execution + // will start on the workflow's Target Version, with AUTO_UPGRADE behavior. + // On the first workflow task completion of the new run, the workflow will assume + // the behavior specified for that workflow type on the Target Version. If that + // behavior is also PINNED_UNTIL_CONTINUE_AS_NEW, the new run will now be pinned to + // that version until the next time it continues-as-new. + // + // When the Target Version of a PINNED_UNTIL_CONTINUE_AS_NEW workflow is different + // from its Pinned Version, the workflow's continue_as_new_suggested flag will be true, + // so that these workflows can tell when continuing-as-new would cause a version change. + VERSIONING_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 3; +} + +// SuggestContinueAsNewReason specifies why SuggestContinueAsNew is true. +enum SuggestContinueAsNewReason { + SUGGEST_CONTINUE_AS_NEW_REASON_UNSPECIFIED = 0; + + // Workflow History size is getting too large. + SUGGEST_CONTINUE_AS_NEW_REASON_HISTORY_SIZE_TOO_LARGE = 1; + + // Workflow History event count is getting too large. + SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_HISTORY_EVENTS = 2; + + // Workflow's count of completed plus in-flight updates is too large. + SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES = 3; + + // Workflow's Target Worker Deployment Version is different from its + // Pinned Version and the workflow's Versioning Behavior is PinnedUntilContinueAsNew. + SUGGEST_CONTINUE_AS_NEW_REASON_TARGET_WORKER_DEPLOYMENT_VERSION_CHANGED = 4; } diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index bf477f2c..0fb26818 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -270,9 +270,14 @@ message WorkflowTaskStartedEventAttributes { // In that case, matching will continue to deliver the task to worker. Without this field, history // service would return AlreadyStarted error, and matching would drop the task. string request_id = 3; - // True if this workflow should continue-as-new soon because its history size (in - // either event count or bytes) is getting large. + // True if this workflow should continue-as-new soon. Reasons for this could be: + // - History size (in either event count or bytes) is getting large + // - Total number of completed and in-flight updates on the workflow is too large + // - Workflow's Target Version is different from its Pinned Version, and the Versioning Behavior is PinnedUntilContinueAsNew bool suggest_continue_as_new = 4; + // The reason(s) that suggest_continue_as_new is true, if it is. + // Nil if suggest_continue_as_new is false. + repeated temporal.api.enums.v1.SuggestContinueAsNewReason suggest_continue_as_new_reasons = 8; // Total history size in bytes, which the workflow might use to decide when to // continue-as-new regardless of the suggestion. Note that history event count is // just the event id of this event, so we don't include it explicitly here. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 94ea33a7..0f061600 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -553,21 +553,31 @@ message WorkflowExecutionOptions { } // Used to override the versioning behavior (and pinned deployment version, if applicable) of a -// specific workflow execution. If set, takes precedence over the worker-sent values. See -// `WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call -// `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` -// to indicate that it should be mutated. -// Pinned overrides are automatically inherited by child workflows, continue-as-new workflows, -// workflow retries, and cron workflows. +// specific workflow execution. If set, this override takes precedence over worker-sent values. +// See `WorkflowExecutionInfo.VersioningInfo` for more information. +// +// To remove the override, call `UpdateWorkflowExecutionOptions` with a null +// `VersioningOverride`, and use the `update_mask` to indicate that it should be mutated. +// +// Pinning behavior overrides (PINNED and PINNED_UNTIL_CONTINUE_AS_NEW) are automatically inherited +// by child workflows, workflow retries, and cron workflows. +// +// For continue-as-new: +// - PINNED overrides are inherited by the new run. +// - PINNED_UNTIL_CONTINUE_AS_NEW overrides are *not* inherited; after continue-as-new, +// versioning behavior falls back to worker-sent values. message VersioningOverride { - // Indicates whether to override the workflow to be AutoUpgrade or Pinned. + // Indicates whether to override the workflow to be AutoUpgrade or use a pinning behavior. oneof override { - // Send the next workflow task to the Version specified in the override. - PinnedOverride pinned = 3; - // Send the next workflow task to the Current Deployment Version - // of its Task Queue when the next workflow task is dispatched. - bool auto_upgrade = 4; + // Override the workflow to use a pinning behavior, optionally specifying a pinned + // deployment version. + PinnedOverride pinned = 3; + + // Override the workflow to use AutoUpgrade. The next workflow task will be sent + // to the current deployment version of the workflow's task queue. + bool auto_upgrade = 4; } + // Required. // Deprecated. Use `override`. temporal.api.enums.v1.VersioningBehavior behavior = 1 [deprecated = true]; @@ -583,20 +593,76 @@ message VersioningOverride { // Deprecated. Use `override.pinned.version`. string pinned_version = 9 [deprecated = true]; + // Describes which pinning behavior to apply and, when needed, which WorkerDeploymentVersion to pin to. message PinnedOverride { - // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. - // See `PinnedOverrideBehavior` for details. - PinnedOverrideBehavior behavior = 1; - // Required. - temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; + // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. + // See `PinnedOverrideBehavior` for details. + PinnedOverrideBehavior behavior = 1; + + // Required if the target workflow is not already pinned to a version. + // + // If the target workflow is already using a pinning behavior and this field is omitted, + // the effective pinned version will be the existing pinned version. + // + // If the target workflow is not using a pinning behavior and this field is omitted, + // the override request will be rejected. + temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; + + // Required if behavior is PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + // Ignored if behavior is not PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING. + // We will reject overrides that have PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING PinnedOverrideBehavior + // and UNSPECIFIED NonPinningPolicy before the batch even starts, but if it somehow sneaks in, + // UNSPECIFIED will be treated the same as REJECT. + NonPinningPolicy if_not_pinning = 3; } - // Used to specify different sub-types of Pinned override that we plan to add in the future. + // "Pinning behaviors" refers to behaviors in which a workflow is explicitly assigned + // to a particular version. Currently, the pinning behaviors are: + // - PINNED + // - PINNED_UNTIL_CONTINUE_AS_NEW + // + // `PinnedOverrideBehavior` controls how the override interacts with existing pinning + // behaviors and with workflows that are not currently pinned. enum PinnedOverrideBehavior { - // Unspecified. - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; - // Override workflow behavior to be Pinned. - PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; + // Unspecified behavior. + PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; + + // Force the workflow to use the PINNED pinning behavior, regardless of its current + // versioning behavior. + PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; + + // Force the workflow to use the PINNED_UNTIL_CONTINUE_AS_NEW pinning behavior, + // regardless of its current versioning behavior. + PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; + + // If the workflow is already using a pinning behavior (PINNED or + // PINNED_UNTIL_CONTINUE_AS_NEW), keep its existing behavior. + // Use if_not_pinning to specify how to treat other workflows. + PINNED_OVERRIDE_BEHAVIOR_KEEP_IF_PINNING = 3; + } + + // Describes how a Pinning behavior override that keeps original pinning behavior + // should be applied to workflows that do not have a pinning behavior. + // This applies to all workflows that have not yet completed their first workflow + // task, because only after first-workflow-task-completion does the server know the + // behavior of a workflow execution. + enum NonPinningPolicy { + // Unspecified. + NON_PINNING_POLICY_UNSPECIFIED = 0; + + // Reject the override at apply time. + NON_PINNING_POLICY_REJECT = 1; + + // Accept the override at apply time, but ignore it for workflows that do not + // have a pinning behavior. Once a workflow's behavior is known, the override + // will only affect it if that behavior is a pinning behavior. + NON_PINNING_POLICY_IGNORE = 2; + + // Use Pinned. + NON_PINNING_POLICY_PINNED = 3; + + // Use PinnedUntilContinueAsNew. + NON_PINNING_POLICY_PINNED_UNTIL_CONTINUE_AS_NEW = 4; } }