all: Add automatic deferred action support for unknown provider configuration

.changes/unreleased/FEATURES-20240520-180458.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'provider: Add `Deferred` field to `ConfigureResponse` 
+  which indicates a provider deferred action to the Terraform client'
+time: 2024-05-20T18:04:58.852448-04:00
+custom:
+  Issue: "1002"

.changes/unreleased/FEATURES-20240520-180735.yaml

@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'provider: Add `ClientCapabilities` field to `ConfigureRequest` which specifies
+  optionally supported protocol features for the Terraform client'
+time: 2024-05-20T18:07:35.862641-04:00
+custom:
+  Issue: "1002"

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/fromproto6/planresourcechange.go

@@ -17,7 +17,7 @@ import (
 
 // PlanResourceChangeRequest returns the *fwserver.PlanResourceChangeRequest
 // equivalent of a *tfprotov6.PlanResourceChangeRequest.
-func PlanResourceChangeRequest(ctx context.Context, proto6 *tfprotov6.PlanResourceChangeRequest, reqResource resource.Resource, resourceSchema fwschema.Schema, providerMetaSchema fwschema.Schema) (*fwserver.PlanResourceChangeRequest, diag.Diagnostics) {
+func PlanResourceChangeRequest(ctx context.Context, proto6 *tfprotov6.PlanResourceChangeRequest, reqResource resource.Resource, resourceSchema fwschema.Schema, providerMetaSchema fwschema.Schema, resourceBehavior resource.ResourceBehavior) (*fwserver.PlanResourceChangeRequest, diag.Diagnostics) {
 	if proto6 == nil {
 		return nil, nil
 	}
@@ -39,6 +39,7 @@ func PlanResourceChangeRequest(ctx context.Context, proto6 *tfprotov6.PlanResour
 	}
 
 	fw := &fwserver.PlanResourceChangeRequest{
+		ResourceBehavior:   resourceBehavior,
 		ResourceSchema:     resourceSchema,
 		Resource:           reqResource,
 		ClientCapabilities: ModifyPlanClientCapabilities(proto6.ClientCapabilities),

internal/fromproto6/planresourcechange_test.go

@@ -56,6 +56,7 @@ func TestPlanResourceChangeRequest(t *testing.T) {
 
 	testCases := map[string]struct {
 		input               *tfprotov6.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:          &tfprotov6.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 := fromproto6.PlanResourceChangeRequest(context.Background(), testCase.input, testCase.resource, testCase.resourceSchema, testCase.providerMetaSchema)
+			got, diags := fromproto6.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)