all: Add support for Manual Deferred Actions

.changes/unreleased/FEATURES-20240508-105105.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'resource: Add `DeferredResponse` field to `ReadResponse`, `ModifyPlanResponse`, and `ImportStateResponse`
+  which indicates a resource deferred action to the Terraform client'
+time: 2024-05-08T10:51:05.90518-04:00
+custom:
+  Issue: "999"

.changes/unreleased/FEATURES-20240508-105141.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'datasource: Add `DeferredResponse` field to `ReadResponse` which indicates a data source deferred action 
+  to the Terraform client'
+time: 2024-05-08T10:51:41.663935-04:00
+custom:
+  Issue: "999"

.changes/unreleased/FEATURES-20240508-110715.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'resource: Add `ClientCapabilities` field to `ReadRequest`, `ModifyPlanRequest`, and `ImportStateRequest`
+  which specifies optionally supported protocol features for the Terraform client'
+time: 2024-05-08T11:07:15.955126-04:00
+custom:
+  Issue: "999"

.changes/unreleased/FEATURES-20240508-111023.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'datasource: Add `ClientCapabilities` field to `ReadRequest` which specifies
+  optionally supported protocol features for the Terraform client'
+time: 2024-05-08T11:10:23.66584-04:00
+custom:
+  Issue: "999"

datasource/deferred.go

@@ -0,0 +1,44 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package datasource
+
+const (
+	// DeferredReasonUnknown is used to indicate an invalid `DeferredReason`.
+	// Provider developers should not use it.
+	DeferredReasonUnknown DeferredReason = 0
+
+	// DeferredReasonResourceConfigUnknown is used to indicate that the resource configuration
+	// is partially unknown and the real values need to be known before the change can be planned.
+	DeferredReasonResourceConfigUnknown DeferredReason = 1
+
+	// DeferredReasonProviderConfigUnknown is used to indicate that the provider configuration
+	// is partially unknown and the real values need to be known before the change can be planned.
+	DeferredReasonProviderConfigUnknown DeferredReason = 2
+
+	// DeferredReasonAbsentPrereq is used to indicate that a hard dependency has not been satisfied.
+	DeferredReasonAbsentPrereq DeferredReason = 3
+)
+
+// DeferredResponse is used to indicate to Terraform that a change needs to be deferred for a reason.
+type DeferredResponse struct {
+	// Reason is the reason for deferring the change.
+	Reason DeferredReason
+}
+
+// DeferredReason represents different reasons for deferring a change.
+type DeferredReason int32
+
+func (d DeferredReason) String() string {
+	switch d {
+	case 0:
+		return "Unknown"
+	case 1:
+		return "Resource Config Unknown"
+	case 2:
+		return "Provider Config Unknown"
+	case 3:
+		return "Absent Prerequisite"
+	}
+	return "Unknown"
+}

datasource/read.go

@@ -8,6 +8,15 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
 )
 
+// ReadClientCapabilities allows Terraform to publish information
+// regarding optionally supported protocol features for the ReadDataSource RPC,
+// such as forward-compatible Terraform behavior changes.
+type ReadClientCapabilities struct {
+	// DeferralAllowed indicates whether the Terraform client initiating
+	// the request allows a deferral response.
+	DeferralAllowed bool
+}
+
 // ReadRequest represents a request for the provider to read a data
 // source, i.e., update values in state according to the real state of the
 // data source. An instance of this request struct is supplied as an argument
@@ -22,6 +31,10 @@ type ReadRequest struct {
 
 	// ProviderMeta is metadata from the provider_meta block of the module.
 	ProviderMeta tfsdk.Config
+
+	// ClientCapabilities defines optionally supported protocol features for the
+	// ReadDataSource RPC, such as forward-compatible Terraform behavior changes.
+	ClientCapabilities *ReadClientCapabilities
 }
 
 // ReadResponse represents a response to a ReadRequest. An
@@ -37,4 +50,11 @@ type ReadResponse struct {
 	// source. An empty slice indicates a successful operation with no
 	// warnings or errors generated.
 	Diagnostics diag.Diagnostics
+
+	// DeferredResponse indicates that Terraform should defer
+	// importing this resource.
+	//
+	// This field can only be set if
+	// `(datasource.ReadRequest.ReadClientCapabilities).DeferralAllowed` is true.
+	DeferredResponse *DeferredResponse
 }

internal/fromproto5/importresourcestate.go

@@ -6,18 +6,19 @@ package fromproto5
 import (
 	"context"
 
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
 )
 
 // ImportResourceStateRequest returns the *fwserver.ImportResourceStateRequest
 // equivalent of a *tfprotov5.ImportResourceStateRequest.
-func ImportResourceStateRequest(ctx context.Context, proto5 *tfprotov5.ImportResourceStateRequest, resource resource.Resource, resourceSchema fwschema.Schema) (*fwserver.ImportResourceStateRequest, diag.Diagnostics) {
+func ImportResourceStateRequest(ctx context.Context, proto5 *tfprotov5.ImportResourceStateRequest, reqResource resource.Resource, resourceSchema fwschema.Schema) (*fwserver.ImportResourceStateRequest, diag.Diagnostics) {
 	if proto5 == nil {
 		return nil, nil
 	}
@@ -44,9 +45,15 @@ func ImportResourceStateRequest(ctx context.Context, proto5 *tfprotov5.ImportRes
 			Schema: resourceSchema,
 		},
 		ID:       proto5.ID,
-		Resource: resource,
+		Resource: reqResource,
 		TypeName: proto5.TypeName,
 	}
 
+	if proto5.ClientCapabilities != nil {
+		fw.ClientCapabilities = &resource.ImportStateClientCapabilities{
+			DeferralAllowed: proto5.ClientCapabilities.DeferralAllowed,
+		}
+	}
+
 	return fw, diags
 }

internal/fromproto5/importresourcestate_test.go

@@ -8,15 +8,16 @@ import (
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fromproto5"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
 	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
 )
 
 func TestImportResourceStateRequest(t *testing.T) {
@@ -86,6 +87,22 @@ func TestImportResourceStateRequest(t *testing.T) {
 				TypeName:   "test_resource",
 			},
 		},
+		"client-capabilities": {
+			input: &tfprotov5.ImportResourceStateRequest{
+				ID: "test-id",
+				ClientCapabilities: &tfprotov5.ImportResourceStateClientCapabilities{
+					DeferralAllowed: true,
+				},
+			},
+			resourceSchema: testFwSchema,
+			expected: &fwserver.ImportResourceStateRequest{
+				EmptyState: testFwEmptyState,
+				ID:         "test-id",
+				ClientCapabilities: &resource.ImportStateClientCapabilities{
+					DeferralAllowed: true,
+				},
+			},
+		},
 	}
 
 	for name, testCase := range testCases {

internal/fromproto5/plan.go

@@ -6,11 +6,12 @@ package fromproto5
 import (
 	"context"
 
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschemadata"
 	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
 )
 
 // Plan returns the *tfsdk.Plan for a *tfprotov5.DynamicValue and

internal/fromproto5/planresourcechange.go

@@ -17,7 +17,7 @@ import (
 
 // PlanResourceChangeRequest returns the *fwserver.PlanResourceChangeRequest
 // equivalent of a *tfprotov5.PlanResourceChangeRequest.
-func PlanResourceChangeRequest(ctx context.Context, proto5 *tfprotov5.PlanResourceChangeRequest, resource resource.Resource, resourceSchema fwschema.Schema, providerMetaSchema fwschema.Schema) (*fwserver.PlanResourceChangeRequest, diag.Diagnostics) {
+func PlanResourceChangeRequest(ctx context.Context, proto5 *tfprotov5.PlanResourceChangeRequest, reqResource resource.Resource, resourceSchema fwschema.Schema, providerMetaSchema fwschema.Schema) (*fwserver.PlanResourceChangeRequest, diag.Diagnostics) {
 	if proto5 == nil {
 		return nil, nil
 	}
@@ -40,7 +40,7 @@ func PlanResourceChangeRequest(ctx context.Context, proto5 *tfprotov5.PlanResour
 
 	fw := &fwserver.PlanResourceChangeRequest{
 		ResourceSchema: resourceSchema,
-		Resource:       resource,
+		Resource:       reqResource,
 	}
 
 	config, configDiags := Config(ctx, proto5.Config, resourceSchema)
@@ -73,5 +73,11 @@ func PlanResourceChangeRequest(ctx context.Context, proto5 *tfprotov5.PlanResour
 
 	fw.PriorPrivate = privateData
 
+	if proto5.ClientCapabilities != nil {
+		fw.ClientCapabilities = &resource.ModifyPlanClientCapabilities{
+			DeferralAllowed: proto5.ClientCapabilities.DeferralAllowed,
+		}
+	}
+
 	return fw, diags
 }

internal/fromproto5/planresourcechange_test.go

@@ -54,6 +54,8 @@ func TestPlanResourceChangeRequest(t *testing.T) {
 
 	testProviderData := privatestate.MustProviderData(context.Background(), testProviderKeyValue)
 
+	testClientCapabilities := tfprotov5.PlanResourceChangeClientCapabilities{DeferralAllowed: true}
+
 	testCases := map[string]struct {
 		input               *tfprotov5.PlanResourceChangeRequest
 		resourceSchema      fwschema.Schema
@@ -217,6 +219,18 @@ func TestPlanResourceChangeRequest(t *testing.T) {
 				ResourceSchema: testFwSchema,
 			},
 		},
+		"client-capabilities": {
+			input: &tfprotov5.PlanResourceChangeRequest{
+				ClientCapabilities: &testClientCapabilities,
+			},
+			resourceSchema: testFwSchema,
+			expected: &fwserver.PlanResourceChangeRequest{
+				ClientCapabilities: &resource.ModifyPlanClientCapabilities{
+					DeferralAllowed: true,
+				},
+				ResourceSchema: testFwSchema,
+			},
+		},
 	}
 
 	for name, testCase := range testCases {

internal/fromproto5/readdatasource.go

@@ -6,11 +6,12 @@ package fromproto5
 import (
 	"context"
 
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
 )
 
 // ReadDataSourceRequest returns the *fwserver.ReadDataSourceRequest
@@ -53,5 +54,11 @@ func ReadDataSourceRequest(ctx context.Context, proto5 *tfprotov5.ReadDataSource
 
 	fw.ProviderMeta = providerMeta
 
+	if proto5.ClientCapabilities != nil {
+		fw.ClientCapabilities = &datasource.ReadClientCapabilities{
+			DeferralAllowed: proto5.ClientCapabilities.DeferralAllowed,
+		}
+	}
+
 	return fw, diags
 }

internal/fromproto5/readdatasource_test.go

@@ -1,4 +1,5 @@
 // Copyright (c) HashiCorp, Inc.
+
 // SPDX-License-Identifier: MPL-2.0
 
 package fromproto5_test
@@ -8,15 +9,16 @@ import (
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fromproto5"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
 	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
 )
 
 func TestReadDataSourceRequest(t *testing.T) {
@@ -46,6 +48,8 @@ func TestReadDataSourceRequest(t *testing.T) {
 		},
 	}
 
+	testClientCapabilities := tfprotov5.ReadDataSourceClientCapabilities{DeferralAllowed: true}
+
 	testCases := map[string]struct {
 		input               *tfprotov5.ReadDataSourceRequest
 		dataSourceSchema    fwschema.Schema
@@ -135,6 +139,18 @@ func TestReadDataSourceRequest(t *testing.T) {
 				},
 			},
 		},
+		"client-capabilities": {
+			input: &tfprotov5.ReadDataSourceRequest{
+				ClientCapabilities: &testClientCapabilities,
+			},
+			dataSourceSchema: testFwSchema,
+			expected: &fwserver.ReadDataSourceRequest{
+				DataSourceSchema: testFwSchema,
+				ClientCapabilities: &datasource.ReadClientCapabilities{
+					DeferralAllowed: true,
+				},
+			},
+		},
 	}
 
 	for name, testCase := range testCases {

internal/fromproto5/readresource.go

@@ -17,15 +17,15 @@ import (
 
 // ReadResourceRequest returns the *fwserver.ReadResourceRequest
 // equivalent of a *tfprotov5.ReadResourceRequest.
-func ReadResourceRequest(ctx context.Context, proto5 *tfprotov5.ReadResourceRequest, resource resource.Resource, resourceSchema fwschema.Schema, providerMetaSchema fwschema.Schema) (*fwserver.ReadResourceRequest, diag.Diagnostics) {
+func ReadResourceRequest(ctx context.Context, proto5 *tfprotov5.ReadResourceRequest, reqResource resource.Resource, resourceSchema fwschema.Schema, providerMetaSchema fwschema.Schema) (*fwserver.ReadResourceRequest, diag.Diagnostics) {
 	if proto5 == nil {
 		return nil, nil
 	}
 
 	var diags diag.Diagnostics
 
 	fw := &fwserver.ReadResourceRequest{
-		Resource: resource,
+		Resource: reqResource,
 	}
 
 	currentState, currentStateDiags := State(ctx, proto5.CurrentState, resourceSchema)
@@ -46,5 +46,11 @@ func ReadResourceRequest(ctx context.Context, proto5 *tfprotov5.ReadResourceRequ
 
 	fw.Private = privateData
 
+	if proto5.ClientCapabilities != nil {
+		fw.ClientCapabilities = &resource.ReadClientCapabilities{
+			DeferralAllowed: proto5.ClientCapabilities.DeferralAllowed,
+		}
+	}
+
 	return fw, diags
 }