diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 0c69f041f..97d10fb8e 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11112,6 +11112,16 @@ } } }, + "VersioningOverrideOneTimeOverride": { + "type": "object", + "properties": { + "targetDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "Required. Worker Deployment Version to receive the one-time Workflow Task." + } + }, + "description": "Routes Workflow Tasks for this execution to `target_deployment_version`\nuntil a Workflow Task completes on that version, then clears the override.\n\nThis does not force the workflow's normal Versioning Behavior to become\nPinned. After the Workflow Task completes on `target_deployment_version`,\nthe workflow execution's normal Versioning Behavior and Deployment Version\nare taken from the worker's completion response.\n\nExample: if an execution is one-time moved from version X to version Y, and\nversion Z later becomes current:\n- if worker Y reports Pinned, the execution stays on Y;\n- if worker Y reports AutoUpgrade, the execution routes to Z on a future\n Workflow Task;\n- if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new,\n the current run stays on Y and the execution can route to Z after\n continue-as-new.\n\nIf no Workflow Task completes on `target_deployment_version`, this override\nremains pending." + }, "VersioningOverridePinnedOverride": { "type": "object", "properties": { @@ -20170,12 +20180,16 @@ "properties": { "pinned": { "$ref": "#/definitions/VersioningOverridePinnedOverride", - "description": "Override the workflow to have Pinned behavior." + "description": "Override the workflow to have Pinned behavior. This is a sticky override:\nWorkflow Tasks continue to route according to this override until it is\nexplicitly removed." }, "autoUpgrade": { "type": "boolean", "description": "Override the workflow to have AutoUpgrade behavior." }, + "oneTime": { + "$ref": "#/definitions/VersioningOverrideOneTimeOverride", + "description": "Override Workflow Task routing to a specific Worker Deployment Version until\none Workflow Task completes there. After completion, the workflow execution's\nVersioning Behavior and Deployment Version come from the worker's completion\nresponse." + }, "behavior": { "$ref": "#/definitions/v1VersioningBehavior", "description": "Required.\nDeprecated. Use `override`." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index bbc00035b..8f209c6ff 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -18362,10 +18362,23 @@ components: pinned: allOf: - $ref: '#/components/schemas/VersioningOverride_PinnedOverride' - description: Override the workflow to have Pinned behavior. + description: |- + Override the workflow to have Pinned behavior. This is a sticky override: + Workflow Tasks continue to route according to this override until it is + explicitly removed. autoUpgrade: type: boolean description: Override the workflow to have AutoUpgrade behavior. + oneTime: + allOf: + - $ref: '#/components/schemas/VersioningOverride_OneTimeOverride' + description: |- + Override Workflow Task routing to a specific Worker Deployment Version until + one Workflow Task completes there. After completion, the workflow execution's + Versioning Behavior and Deployment Version come from the worker's completion + response. + (-- api-linter: core::0142::time-field-type=disabled + aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --) behavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED @@ -18400,6 +18413,33 @@ components: Pinned behavior overrides are automatically inherited by child workflows, workflow retries, continue-as-new workflows, and cron workflows. + VersioningOverride_OneTimeOverride: + type: object + properties: + targetDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: Required. Worker Deployment Version to receive the one-time Workflow Task. + description: |- + Routes Workflow Tasks for this execution to `target_deployment_version` + until a Workflow Task completes on that version, then clears the override. + + This does not force the workflow's normal Versioning Behavior to become + Pinned. After the Workflow Task completes on `target_deployment_version`, + the workflow execution's normal Versioning Behavior and Deployment Version + are taken from the worker's completion response. + + Example: if an execution is one-time moved from version X to version Y, and + version Z later becomes current: + - if worker Y reports Pinned, the execution stays on Y; + - if worker Y reports AutoUpgrade, the execution routes to Z on a future + Workflow Task; + - if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new, + the current run stays on Y and the execution can route to Z after + continue-as-new. + + If no Workflow Task completes on `target_deployment_version`, this override + remains pending. VersioningOverride_PinnedOverride: type: object properties: diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 4d35cb74b..c09370f7c 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -609,11 +609,21 @@ message WorkflowExecutionOptions { message VersioningOverride { // Indicates whether to override the workflow to be AutoUpgrade or Pinned. oneof override { - // Override the workflow to have Pinned behavior. + // Override the workflow to have Pinned behavior. This is a sticky override: + // Workflow Tasks continue to route according to this override until it is + // explicitly removed. PinnedOverride pinned = 3; // Override the workflow to have AutoUpgrade behavior. bool auto_upgrade = 4; + + // Override Workflow Task routing to a specific Worker Deployment Version until + // one Workflow Task completes there. After completion, the workflow execution's + // Versioning Behavior and Deployment Version come from the worker's completion + // response. + // (-- api-linter: core::0142::time-field-type=disabled + // aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --) + OneTimeOverride one_time = 5; } // Required. @@ -647,6 +657,30 @@ message VersioningOverride { temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; } + // Routes Workflow Tasks for this execution to `target_deployment_version` + // until a Workflow Task completes on that version, then clears the override. + // + // This does not force the workflow's normal Versioning Behavior to become + // Pinned. After the Workflow Task completes on `target_deployment_version`, + // the workflow execution's normal Versioning Behavior and Deployment Version + // are taken from the worker's completion response. + // + // Example: if an execution is one-time moved from version X to version Y, and + // version Z later becomes current: + // - if worker Y reports Pinned, the execution stays on Y; + // - if worker Y reports AutoUpgrade, the execution routes to Z on a future + // Workflow Task; + // - if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new, + // the current run stays on Y and the execution can route to Z after + // continue-as-new. + // + // If no Workflow Task completes on `target_deployment_version`, this override + // remains pending. + message OneTimeOverride { + // Required. Worker Deployment Version to receive the one-time Workflow Task. + temporal.api.deployment.v1.WorkerDeploymentVersion target_deployment_version = 1; + } + enum PinnedOverrideBehavior { // Unspecified. PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0;