all: Add automatic deferred action support for unknown provider configuration

internal/fromproto5/client_capabilities.go

@@ -7,9 +7,23 @@ import (
 	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
 
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/provider"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 )
 
+func ConfigureProviderClientCapabilities(in *tfprotov5.ConfigureProviderClientCapabilities) provider.ConfigureProviderClientCapabilities {
+	if in == nil {
+		// Client did not indicate any supported capabilities
+		return provider.ConfigureProviderClientCapabilities{
+			DeferralAllowed: false,
+		}
+	}
+
+	return provider.ConfigureProviderClientCapabilities{
+		DeferralAllowed: in.DeferralAllowed,
+	}
+}
+
 func ReadDataSourceClientCapabilities(in *tfprotov5.ReadDataSourceClientCapabilities) datasource.ReadClientCapabilities {
 	if in == nil {
 		// Client did not indicate any supported capabilities

internal/fromproto5/configureprovider.go

@@ -6,10 +6,11 @@ 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/provider"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
 )
 
 // ConfigureProviderRequest returns the *fwserver.ConfigureProviderRequest
@@ -20,7 +21,8 @@ func ConfigureProviderRequest(ctx context.Context, proto5 *tfprotov5.ConfigurePr
 	}
 
 	fw := &provider.ConfigureRequest{
-		TerraformVersion: proto5.TerraformVersion,
+		TerraformVersion:   proto5.TerraformVersion,
+		ClientCapabilities: ConfigureProviderClientCapabilities(proto5.ClientCapabilities),
 	}
 
 	config, diags := Config(ctx, proto5.Config, providerSchema)

internal/fromproto5/configureprovider_test.go

@@ -8,14 +8,15 @@ 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/provider"
 	"github.com/hashicorp/terraform-plugin-framework/provider/schema"
 	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
 )
 
 func TestConfigureProviderRequest(t *testing.T) {
@@ -94,6 +95,26 @@ func TestConfigureProviderRequest(t *testing.T) {
 				TerraformVersion: "99.99.99",
 			},
 		},
+		"client-capabilities": {
+			input: &tfprotov5.ConfigureProviderRequest{
+				ClientCapabilities: &tfprotov5.ConfigureProviderClientCapabilities{
+					DeferralAllowed: true,
+				},
+			},
+			expected: &provider.ConfigureRequest{
+				ClientCapabilities: provider.ConfigureProviderClientCapabilities{
+					DeferralAllowed: true,
+				},
+			},
+		},
+		"client-capabilities-unset": {
+			input: &tfprotov5.ConfigureProviderRequest{},
+			expected: &provider.ConfigureRequest{
+				ClientCapabilities: provider.ConfigureProviderClientCapabilities{
+					DeferralAllowed: false,
+				},
+			},
+		},
 	}
 
 	for name, testCase := range testCases {

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, reqResource 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, resourceBehavior resource.ResourceBehavior) (*fwserver.PlanResourceChangeRequest, diag.Diagnostics) {
 	if proto5 == nil {
 		return nil, nil
 	}
@@ -39,6 +39,7 @@ func PlanResourceChangeRequest(ctx context.Context, proto5 *tfprotov5.PlanResour
 	}
 
 	fw := &fwserver.PlanResourceChangeRequest{
+		ResourceBehavior:   resourceBehavior,
 		ResourceSchema:     resourceSchema,
 		Resource:           reqResource,
 		ClientCapabilities: ModifyPlanClientCapabilities(proto5.ClientCapabilities),

internal/fromproto5/planresourcechange_test.go

@@ -56,6 +56,7 @@ func TestPlanResourceChangeRequest(t *testing.T) {
 
 	testCases := map[string]struct {
 		input               *tfprotov5.PlanResourceChangeRequest
+		resourceBehavior    resource.ResourceBehavior
 		resourceSchema      fwschema.Schema
 		resource            resource.Resource
 		providerMetaSchema  fwschema.Schema
@@ -241,6 +242,23 @@ func TestPlanResourceChangeRequest(t *testing.T) {
 				ResourceSchema: testFwSchema,
 			},
 		},
+		"resource-behavior": {
+			input:          &tfprotov5.PlanResourceChangeRequest{},
+			resourceSchema: testFwSchema,
+			resourceBehavior: resource.ResourceBehavior{
+				ProviderDeferred: resource.ProviderDeferredBehavior{
+					EnablePlanModification: true,
+				},
+			},
+			expected: &fwserver.PlanResourceChangeRequest{
+				ResourceBehavior: resource.ResourceBehavior{
+					ProviderDeferred: resource.ProviderDeferredBehavior{
+						EnablePlanModification: true,
+					},
+				},
+				ResourceSchema: testFwSchema,
+			},
+		},
 	}
 
 	for name, testCase := range testCases {
@@ -249,7 +267,7 @@ func TestPlanResourceChangeRequest(t *testing.T) {
 		t.Run(name, func(t *testing.T) {
 			t.Parallel()
 
-			got, diags := fromproto5.PlanResourceChangeRequest(context.Background(), testCase.input, testCase.resource, testCase.resourceSchema, testCase.providerMetaSchema)
+			got, diags := fromproto5.PlanResourceChangeRequest(context.Background(), testCase.input, testCase.resource, testCase.resourceSchema, testCase.providerMetaSchema, testCase.resourceBehavior)
 
 			if diff := cmp.Diff(got, testCase.expected, cmp.AllowUnexported(privatestate.ProviderData{})); diff != "" {
 				t.Errorf("unexpected difference: %s", diff)

internal/fromproto6/client_capabilities.go

@@ -7,9 +7,23 @@ import (
 	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
 
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/provider"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 )
 
+func ConfigureProviderClientCapabilities(in *tfprotov6.ConfigureProviderClientCapabilities) provider.ConfigureProviderClientCapabilities {
+	if in == nil {
+		// Client did not indicate any supported capabilities
+		return provider.ConfigureProviderClientCapabilities{
+			DeferralAllowed: false,
+		}
+	}
+
+	return provider.ConfigureProviderClientCapabilities{
+		DeferralAllowed: in.DeferralAllowed,
+	}
+}
+
 func ReadDataSourceClientCapabilities(in *tfprotov6.ReadDataSourceClientCapabilities) datasource.ReadClientCapabilities {
 	if in == nil {
 		// Client did not indicate any supported capabilities

internal/fromproto6/configureprovider.go

@@ -6,10 +6,11 @@ package fromproto6
 import (
 	"context"
 
+	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
+
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
 	"github.com/hashicorp/terraform-plugin-framework/provider"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
 )
 
 // ConfigureProviderRequest returns the *fwserver.ConfigureProviderRequest
@@ -20,7 +21,8 @@ func ConfigureProviderRequest(ctx context.Context, proto6 *tfprotov6.ConfigurePr
 	}
 
 	fw := &provider.ConfigureRequest{
-		TerraformVersion: proto6.TerraformVersion,
+		TerraformVersion:   proto6.TerraformVersion,
+		ClientCapabilities: ConfigureProviderClientCapabilities(proto6.ClientCapabilities),
 	}
 
 	config, diags := Config(ctx, proto6.Config, providerSchema)

internal/fromproto6/configureprovider_test.go

@@ -8,14 +8,15 @@ import (
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fromproto6"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
 	"github.com/hashicorp/terraform-plugin-framework/provider"
 	"github.com/hashicorp/terraform-plugin-framework/provider/schema"
 	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
-	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
 )
 
 func TestConfigureProviderRequest(t *testing.T) {
@@ -94,6 +95,26 @@ func TestConfigureProviderRequest(t *testing.T) {
 				TerraformVersion: "99.99.99",
 			},
 		},
+		"client-capabilities": {
+			input: &tfprotov6.ConfigureProviderRequest{
+				ClientCapabilities: &tfprotov6.ConfigureProviderClientCapabilities{
+					DeferralAllowed: true,
+				},
+			},
+			expected: &provider.ConfigureRequest{
+				ClientCapabilities: provider.ConfigureProviderClientCapabilities{
+					DeferralAllowed: true,
+				},
+			},
+		},
+		"client-capabilities-unset": {
+			input: &tfprotov6.ConfigureProviderRequest{},
+			expected: &provider.ConfigureRequest{
+				ClientCapabilities: provider.ConfigureProviderClientCapabilities{
+					DeferralAllowed: false,
+				},
+			},
+		},
 	}
 
 	for name, testCase := range testCases {

internal/fwserver/server.go

@@ -56,6 +56,11 @@ type Server struct {
 	// access from race conditions.
 	dataSourceTypesMutex sync.Mutex
 
+	// deferred indicates an automatic provider deferral. When this is set,
+	// the provider will automatically defer the PlanResourceChange, ReadResource,
+	// ImportResourceState, and ReadDataSource RPCs.
+	deferred *provider.Deferred
+
 	// functionDefinitions is the cached Function Definitions for RPCs that need to
 	// convert data from the protocol. If not found, it will be fetched from the
 	// Function.Definition() method.
@@ -137,6 +142,19 @@ type Server struct {
 	// resourceTypesMutex is a mutex to protect concurrent resourceTypes
 	// access from race conditions.
 	resourceTypesMutex sync.Mutex
+
+	// resourceBehaviors is the cached Resource behaviors for RPCs that need to
+	// control framework-specific logic when interacting with a resource.
+	resourceBehaviors map[string]resource.ResourceBehavior
+
+	// resourceBehaviorsDiags is the cached Diagnostics obtained while populating
+	// resourceBehaviors. This is to ensure any warnings or errors are also
+	// returned appropriately when fetching resourceBehaviors.
+	resourceBehaviorsDiags diag.Diagnostics
+
+	// resourceBehaviorsMutex is a mutex to protect concurrent resourceBehaviors
+	// access from race conditions.
+	resourceBehaviorsMutex sync.Mutex
 }
 
 // DataSource returns the DataSource for a given type name.
@@ -414,6 +432,78 @@ func (s *Server) Resource(ctx context.Context, typeName string) (resource.Resour
 	return resourceFunc(), diags
 }
 
+// ResourceBehavior returns the ResourceBehavior for a given type name.
+func (s *Server) ResourceBehavior(ctx context.Context, typeName string) (resource.ResourceBehavior, diag.Diagnostics) {
+	resourceBehaviors, diags := s.ResourceBehaviors(ctx)
+
+	resourceBehavior, ok := resourceBehaviors[typeName]
+
+	if !ok {
+		diags.AddError(
+			"Resource Type Not Found",
+			fmt.Sprintf("No resource type named %q was found in the provider.", typeName),
+		)
+
+		return resource.ResourceBehavior{}, diags
+	}
+
+	return resourceBehavior, diags
+}
+
+// ResourceBehaviors returns a map of ResourceBehavior. The results are cached
+// on first use.
+func (s *Server) ResourceBehaviors(ctx context.Context) (map[string]resource.ResourceBehavior, diag.Diagnostics) {
+	logging.FrameworkTrace(ctx, "Checking ResourceBehaviors lock")
+	s.resourceBehaviorsMutex.Lock()
+	defer s.resourceBehaviorsMutex.Unlock()
+
+	if s.resourceBehaviors != nil {
+		return s.resourceBehaviors, s.resourceBehaviorsDiags
+	}
+
+	providerTypeName := s.ProviderTypeName(ctx)
+	s.resourceBehaviors = make(map[string]resource.ResourceBehavior)
+
+	resourceFuncs, diags := s.ResourceFuncs(ctx)
+	s.resourceBehaviorsDiags.Append(diags...)
+
+	for _, resourceFunc := range resourceFuncs {
+		res := resourceFunc()
+
+		metadataRequest := resource.MetadataRequest{
+			ProviderTypeName: providerTypeName,
+		}
+		metadataResponse := resource.MetadataResponse{}
+
+		res.Metadata(ctx, metadataRequest, &metadataResponse)
+
+		if metadataResponse.TypeName == "" {
+			s.resourceBehaviorsDiags.AddError(
+				"Resource Type Name Missing",
+				fmt.Sprintf("The %T Resource returned an empty string from the Metadata method. ", res)+
+					"This is always an issue with the provider and should be reported to the provider developers.",
+			)
+			continue
+		}
+
+		logging.FrameworkTrace(ctx, "Found resource type", map[string]interface{}{logging.KeyResourceType: metadataResponse.TypeName})
+
+		if _, ok := s.resourceBehaviors[metadataResponse.TypeName]; ok {
+			s.resourceBehaviorsDiags.AddError(
+				"Duplicate Resource Type Defined",
+				fmt.Sprintf("The %s resource type name was returned for multiple resources. ", metadataResponse.TypeName)+
+					"Resource type names must be unique. "+
+					"This is always an issue with the provider and should be reported to the provider developers.",
+			)
+			continue
+		}
+
+		s.resourceBehaviors[metadataResponse.TypeName] = metadataResponse.ResourceBehavior
+	}
+
+	return s.resourceBehaviors, s.resourceBehaviorsDiags
+}
+
 // ResourceFuncs returns a map of Resource functions. The results are cached
 // on first use.
 func (s *Server) ResourceFuncs(ctx context.Context) (map[string]func() resource.Resource, diag.Diagnostics) {

internal/fwserver/server_configureprovider.go

@@ -22,6 +22,18 @@ func (s *Server) ConfigureProvider(ctx context.Context, req *provider.ConfigureR
 
 	logging.FrameworkTrace(ctx, "Called provider defined Provider Configure")
 
+	if resp.Deferred != nil {
+		if !req.ClientCapabilities.DeferralAllowed {
+			resp.Diagnostics.AddError("Invalid Deferred Provider Response",
+				"Provider configured a deferred response for all resources and data sources but the Terraform request "+
+					"did not indicate support for deferred actions. This is an issue with the provider and should be reported to the provider developers.")
+		} else {
+			logging.FrameworkDebug(ctx, "Provider has configured a deferred response, "+
+				"all associated resources and data sources will automatically return a deferred response.")
+		}
+	}
+
+	s.deferred = resp.Deferred
 	s.DataSourceConfigureData = resp.DataSourceData
 	s.ResourceConfigureData = resp.ResourceData
 }