Versioning 3 (#1744)

Author: antlai-temporal

.github/workflows/ci.yml

@@ -88,6 +88,9 @@ jobs:
       - name: Docker compose - integration tests
         if: ${{ matrix.testDockerCompose }}
         run: go run . integration-test
+        env:
+          # TODO(antlai-temporal): Remove this flag once server 1.26.2 released.
+          DISABLE_DEPLOYMENT_TESTS: "1"
         working-directory: ./internal/cmd/build
 
   cloud-test:

client/client.go

@@ -46,6 +46,36 @@ import (
 	"go.temporal.io/sdk/internal/common/metrics"
 )
 
+// DeploymentReachability specifies which category of tasks may reach a worker
+// associated with a deployment, simplifying safe decommission.
+// NOTE: Experimental
+type DeploymentReachability = internal.DeploymentReachability
+
+const (
+	// DeploymentReachabilityUnspecified - Reachability level not specified.
+	// NOTE: Experimental
+	DeploymentReachabilityUnspecified = internal.DeploymentReachabilityUnspecified
+
+	// DeploymentReachabilityReachable - The deployment is reachable by new
+	// and/or open workflows. The deployment cannot be decommissioned safely.
+	// NOTE: Experimental
+	DeploymentReachabilityReachable = internal.DeploymentReachabilityReachable
+
+	// DeploymentReachabilityClosedWorkflows - The deployment is not reachable
+	// by new or open workflows, but might be still needed by
+	// Queries sent to closed workflows. The deployment can be decommissioned
+	// safely if user does not query closed workflows.
+	// NOTE: Experimental
+	DeploymentReachabilityClosedWorkflows = internal.DeploymentReachabilityClosedWorkflows
+
+	// DeploymentReachabilityUnreachable - The deployment is not reachable by
+	// any workflow because all the workflows who needed this
+	// deployment are out of the retention period. The deployment can be
+	// decommissioned safely.
+	// NOTE: Experimental
+	DeploymentReachabilityUnreachable = internal.DeploymentReachabilityUnreachable
+)
+
 // TaskReachability specifies which category of tasks may reach a worker on a versioned task queue.
 // Used both in a reachability query and its response.
 //
@@ -273,6 +303,97 @@ type (
 	// NOTE: Experimental
 	UpdateWithStartWorkflowOptions = internal.UpdateWithStartWorkflowOptions
 
+	// Deployment identifies a set of workers. This identifier combines
+	// the deployment series name with their Build ID.
+	// NOTE: Experimental
+	Deployment = internal.Deployment
+
+	// DeploymentTaskQueueInfo describes properties of the Task Queues involved
+	// in a deployment.
+	// NOTE: Experimental
+	DeploymentTaskQueueInfo = internal.DeploymentTaskQueueInfo
+
+	// DeploymentInfo holds information associated with
+	// workers in this deployment.
+	// Workers can poll multiple task queues in a single deployment,
+	// which are listed in this message.
+	// NOTE: Experimental
+	DeploymentInfo = internal.DeploymentInfo
+
+	// DeploymentListEntry is a subset of fields from DeploymentInfo.
+	// NOTE: Experimental
+	DeploymentListEntry = internal.DeploymentListEntry
+
+	// DeploymentListIterator is an iterator for deployments.
+	// NOTE: Experimental
+	DeploymentListIterator = internal.DeploymentListIterator
+
+	// DeploymentListOptions are the parameters for configuring listing deployments.
+	// NOTE: Experimental
+	DeploymentListOptions = internal.DeploymentListOptions
+
+	// DeploymentReachabilityInfo extends DeploymentInfo with reachability information.
+	// NOTE: Experimental
+	DeploymentReachabilityInfo = internal.DeploymentReachabilityInfo
+
+	// DeploymentMetadataUpdate modifies user-defined metadata entries that describe
+	// a deployment.
+	// NOTE: Experimental
+	DeploymentMetadataUpdate = internal.DeploymentMetadataUpdate
+
+	// DeploymentDescribeOptions provides options for [DeploymentClient.Describe].
+	// NOTE: Experimental
+	DeploymentDescribeOptions = internal.DeploymentDescribeOptions
+
+	// DeploymentDescription is the response type for [DeploymentClient.Describe].
+	// NOTE: Experimental
+	DeploymentDescription = internal.DeploymentDescription
+
+	// DeploymentGetReachabilityOptions provides options for [DeploymentClient.GetReachability].
+	// NOTE: Experimental
+	DeploymentGetReachabilityOptions = internal.DeploymentGetReachabilityOptions
+
+	// DeploymentGetCurrentOptions provides options for [DeploymentClient.GetCurrent].
+	// NOTE: Experimental
+	DeploymentGetCurrentOptions = internal.DeploymentGetCurrentOptions
+
+	// DeploymentGetCurrentResponse is the response type for [DeploymentClient.GetCurrent].
+	// NOTE: Experimental
+	DeploymentGetCurrentResponse = internal.DeploymentGetCurrentResponse
+
+	// DeploymentSetCurrentOptions provides options for [DeploymentClient.SetCurrent].
+	// NOTE: Experimental
+	DeploymentSetCurrentOptions = internal.DeploymentSetCurrentOptions
+
+	// DeploymentSetCurrentResponse is the response type for [DeploymentClient.SetCurrent].
+	// NOTE: Experimental
+	DeploymentSetCurrentResponse = internal.DeploymentSetCurrentResponse
+
+	// DeploymentClient is the server interface to manage deployments.
+	// NOTE: Experimental
+	DeploymentClient = internal.DeploymentClient
+
+	// UpdateWorkflowExecutionOptionsRequest is a request for [Client.UpdateWorkflowExecutionOptions].
+	// NOTE: Experimental
+	UpdateWorkflowExecutionOptionsRequest = internal.UpdateWorkflowExecutionOptionsRequest
+
+	// WorkflowExecutionOptions contains a set of properties of an existing workflow
+	// that can be overriden using [UpdateWorkflowExecutionOptions].
+	// NOTE: Experimental
+	WorkflowExecutionOptions = internal.WorkflowExecutionOptions
+
+	// WorkflowExecutionOptionsChanges describes changes to [WorkflowExecutionOptions]
+	// in the [UpdateWorkflowExecutionOptions] API.
+	// NOTE: Experimental
+	WorkflowExecutionOptionsChanges = internal.WorkflowExecutionOptionsChanges
+
+	// VersioningOverride is a property in [WorkflowExecutionOptions] that changes the versioning
+	// configuration of a specific workflow execution.
+	// If set, it takes precedence over the Versioning Behavior provided with workflow type registration, or
+	// default worker options.
+	// NOTE: Experimental
+	VersioningOverride = internal.VersioningOverride
+
 	// WorkflowUpdateHandle represents a running or completed workflow
 	// execution update and gives the holder access to the outcome of the same.
 	WorkflowUpdateHandle = internal.WorkflowUpdateHandle
@@ -837,6 +958,13 @@ type (
 		//  - WorkflowUpdateServiceTimeoutOrCanceledError
 		UpdateWorkflow(ctx context.Context, options UpdateWorkflowOptions) (WorkflowUpdateHandle, error)
 
+		// UpdateWorkflowExecutionOptions partially overrides the [WorkflowExecutionOptions] of an existing workflow execution
+		// and returns the new [WorkflowExecutionOptions] after applying the changes.
+		// It is intended for building tools that can selectively apply ad-hoc workflow configuration changes.
+		// Use [DescribeWorkflowExecution] to get similar information without modifying options.
+		// NOTE: Experimental
+		UpdateWorkflowExecutionOptions(ctx context.Context, options UpdateWorkflowExecutionOptionsRequest) (WorkflowExecutionOptions, error)
+
 		// UpdateWithStartWorkflow issues an update-with-start request. A
 		// WorkflowIDConflictPolicy must be set in the options. If the specified
 		// workflow execution is not running, then a new workflow execution is
@@ -867,6 +995,10 @@ type (
 		// Schedule creates a new shedule client with the same gRPC connection as this client.
 		ScheduleClient() ScheduleClient
 
+		// DeploymentClient create a new deployment client with the same gRPC connection as this client.
+		// NOTE: Experimental
+		DeploymentClient() DeploymentClient
+
 		// Close client and clean up underlying resources.
 		//
 		// If this client was created via NewClientFromExisting or this client has

internal/client.go

@@ -341,6 +341,12 @@ type (
 		//  - serviceerror.NotFound
 		DescribeWorkflowExecution(ctx context.Context, workflowID, runID string) (*workflowservice.DescribeWorkflowExecutionResponse, error)
 
+		// UpdateWorkflowExecutionOptions partially overrides the [WorkflowExecutionOptions] of an existing workflow execution
+		// and returns the new [WorkflowExecutionOptions] after applying the changes.
+		// It is intended for building tools that can selectively apply ad-hoc workflow configuration changes.
+		// NOTE: Experimental
+		UpdateWorkflowExecutionOptions(ctx context.Context, options UpdateWorkflowExecutionOptionsRequest) (WorkflowExecutionOptions, error)
+
 		// DescribeTaskQueue returns information about the target taskqueue, right now this API returns the
 		// pollers which polled this taskqueue in last few minutes.
 		// The errors it can return:
@@ -429,6 +435,9 @@ type (
 		// Schedule creates a new shedule client with the same gRPC connection as this client.
 		ScheduleClient() ScheduleClient
 
+		// DeploymentClient creates a new deployment client with the same gRPC connection as this client.
+		DeploymentClient() DeploymentClient
+
 		// Close client and clean up underlying resources.
 		Close()
 	}
@@ -757,6 +766,14 @@ type (
 		// NOTE: Experimental
 		StaticDetails string
 
+		// VersioningOverride - Sets the versioning configuration of a specific workflow execution, ignoring current
+		// server or worker default policies. This enables running canary tests without affecting existing workflows.
+		// To unset the override after the workflow is running, use [UpdateWorkflowExecutionOptions].
+		// Optional: defaults to no override.
+		//
+		// NOTE: Experimental
+		VersioningOverride VersioningOverride
+
 		// request ID. Only settable by the SDK - e.g. [temporalnexus.workflowRunOperation].
 		requestID string
 		// workflow completion callback. Only settable by the SDK - e.g. [temporalnexus.workflowRunOperation].

internal/cmd/build/main.go

@@ -145,7 +145,7 @@ func (b *builder) integrationTest() error {
 				Namespace: "integration-test-namespace",
 			},
 			CachedDownload: testsuite.CachedDownload{
-				Version: "v1.1.0",
+				Version: "v1.2.0-versioning.0",
 			},
 			LogLevel: "warn",
 			ExtraArgs: []string{
@@ -160,6 +160,7 @@ func (b *builder) integrationTest() error {
 				"--dynamic-config-value", "system.forceSearchAttributesCacheRefreshOnRead=true",
 				"--dynamic-config-value", "worker.buildIdScavengerEnabled=true",
 				"--dynamic-config-value", "worker.removableBuildIdDurationSinceDefault=1",
+				"--dynamic-config-value", "system.enableDeployments=true",
 				// All of the below is required for Nexus tests.
 				"--http-port", "7243",
 				"--dynamic-config-value", "system.enableNexus=true",