add protocol bindings to external interface

tfprotov5/data_source.go

@@ -87,6 +87,9 @@ type ReadDataSourceRequest struct {
 	//
 	// This configuration will have known values for all fields.
 	ProviderMeta *DynamicValue
+
+	// TODO: doc
+	DeferralAllowed bool
 }
 
 // ReadDataSourceResponse is the response from the provider about the current
@@ -105,4 +108,7 @@ type ReadDataSourceResponse struct {
 	// indicates a successful validation with no warnings or errors
 	// generated.
 	Diagnostics []*Diagnostic
+
+	// TODO: doc
+	Deferred *Deferred
 }

tfprotov5/deferred.go

@@ -0,0 +1,41 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package tfprotov5
+
+const (
+	// TODO: doc
+	DeferredReasonUnknown DeferredReason = 0
+
+	// TODO: doc
+	DeferredReasonResourceConfigUnknown DeferredReason = 1
+
+	// TODO: doc
+	DeferredReasonProviderConfigUnknown DeferredReason = 2
+
+	// TODO: doc
+	DeferredReasonAbsentPrereq DeferredReason = 3
+)
+
+// TODO: doc
+type Deferred struct {
+	// TODO: doc
+	Reason DeferredReason
+}
+
+// TODO: doc
+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_PREREQ"
+	}
+	return "UNKNOWN"
+}

tfprotov5/internal/fromproto/data_source.go

@@ -27,9 +27,10 @@ func ReadDataSourceRequest(in *tfplugin5.ReadDataSource_Request) *tfprotov5.Read
 	}
 
 	resp := &tfprotov5.ReadDataSourceRequest{
-		Config:       DynamicValue(in.Config),
-		ProviderMeta: DynamicValue(in.ProviderMeta),
-		TypeName:     in.TypeName,
+		Config:          DynamicValue(in.Config),
+		ProviderMeta:    DynamicValue(in.ProviderMeta),
+		TypeName:        in.TypeName,
+		DeferralAllowed: in.DeferralAllowed,
 	}
 
 	return resp

tfprotov5/internal/fromproto/data_source_test.go

@@ -51,6 +51,14 @@ func TestReadDataSourceRequest(t *testing.T) {
 				TypeName: "test",
 			},
 		},
+		"DeferralAllowed": {
+			in: &tfplugin5.ReadDataSource_Request{
+				DeferralAllowed: true,
+			},
+			expected: &tfprotov5.ReadDataSourceRequest{
+				DeferralAllowed: true,
+			},
+		},
 	}
 
 	for name, testCase := range testCases {

tfprotov5/internal/fromproto/resource.go

@@ -41,10 +41,11 @@ func ReadResourceRequest(in *tfplugin5.ReadResource_Request) *tfprotov5.ReadReso
 	}
 
 	resp := &tfprotov5.ReadResourceRequest{
-		CurrentState: DynamicValue(in.CurrentState),
-		Private:      in.Private,
-		ProviderMeta: DynamicValue(in.ProviderMeta),
-		TypeName:     in.TypeName,
+		CurrentState:    DynamicValue(in.CurrentState),
+		Private:         in.Private,
+		ProviderMeta:    DynamicValue(in.ProviderMeta),
+		TypeName:        in.TypeName,
+		DeferralAllowed: in.DeferralAllowed,
 	}
 
 	return resp
@@ -62,6 +63,7 @@ func PlanResourceChangeRequest(in *tfplugin5.PlanResourceChange_Request) *tfprot
 		ProposedNewState: DynamicValue(in.ProposedNewState),
 		ProviderMeta:     DynamicValue(in.ProviderMeta),
 		TypeName:         in.TypeName,
+		DeferralAllowed:  in.DeferralAllowed,
 	}
 
 	return resp
@@ -90,8 +92,9 @@ func ImportResourceStateRequest(in *tfplugin5.ImportResourceState_Request) *tfpr
 	}
 
 	resp := &tfprotov5.ImportResourceStateRequest{
-		TypeName: in.TypeName,
-		ID:       in.Id,
+		TypeName:        in.TypeName,
+		ID:              in.Id,
+		DeferralAllowed: in.DeferralAllowed,
 	}
 
 	return resp

tfprotov5/internal/fromproto/resource_test.go

@@ -123,6 +123,14 @@ func TestImportResourceStateRequest(t *testing.T) {
 				TypeName: "test",
 			},
 		},
+		"DeferralAllowed": {
+			in: &tfplugin5.ImportResourceState_Request{
+				DeferralAllowed: true,
+			},
+			expected: &tfprotov5.ImportResourceStateRequest{
+				DeferralAllowed: true,
+			},
+		},
 	}
 
 	for name, testCase := range testCases {
@@ -283,6 +291,14 @@ func TestPlanResourceChangeRequest(t *testing.T) {
 				TypeName: "test",
 			},
 		},
+		"DeferralAllowed": {
+			in: &tfplugin5.PlanResourceChange_Request{
+				DeferralAllowed: true,
+			},
+			expected: &tfprotov5.PlanResourceChangeRequest{
+				DeferralAllowed: true,
+			},
+		},
 	}
 
 	for name, testCase := range testCases {
@@ -347,6 +363,14 @@ func TestReadResourceRequest(t *testing.T) {
 				TypeName: "test",
 			},
 		},
+		"DeferralAllowed": {
+			in: &tfplugin5.ReadResource_Request{
+				DeferralAllowed: true,
+			},
+			expected: &tfprotov5.ReadResourceRequest{
+				DeferralAllowed: true,
+			},
+		},
 	}
 
 	for name, testCase := range testCases {

tfprotov5/internal/toproto/data_source.go

@@ -40,6 +40,7 @@ func ReadDataSource_Response(in *tfprotov5.ReadDataSourceResponse) *tfplugin5.Re
 	resp := &tfplugin5.ReadDataSource_Response{
 		Diagnostics: Diagnostics(in.Diagnostics),
 		State:       DynamicValue(in.State),
+		Deferred:    Deferred(in.Deferred),
 	}
 
 	return resp

tfprotov5/internal/toproto/data_source_test.go

@@ -99,6 +99,19 @@ func TestReadDataSource_Response(t *testing.T) {
 				State:       testTfplugin5DynamicValue(),
 			},
 		},
+		"Deferred": {
+			in: &tfprotov5.ReadDataSourceResponse{
+				Deferred: &tfprotov5.Deferred{
+					Reason: tfprotov5.DeferredReasonResourceConfigUnknown,
+				},
+			},
+			expected: &tfplugin5.ReadDataSource_Response{
+				Diagnostics: []*tfplugin5.Diagnostic{},
+				Deferred: &tfplugin5.Deferred{
+					Reason: tfplugin5.Deferred_RESOURCE_CONFIG_UNKNOWN,
+				},
+			},
+		},
 	}
 
 	for name, testCase := range testCases {
@@ -117,6 +130,7 @@ func TestReadDataSource_Response(t *testing.T) {
 				tfplugin5.Diagnostic{},
 				tfplugin5.DynamicValue{},
 				tfplugin5.ReadDataSource_Response{},
+				tfplugin5.Deferred{},
 			)
 
 			if diff := cmp.Diff(got, testCase.expected, diffOpts); diff != "" {

tfprotov5/internal/toproto/deferred.go

@@ -0,0 +1,21 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package toproto
+
+import (
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5/internal/tfplugin5"
+)
+
+func Deferred(in *tfprotov5.Deferred) *tfplugin5.Deferred {
+	if in == nil {
+		return nil
+	}
+
+	resp := &tfplugin5.Deferred{
+		Reason: tfplugin5.Deferred_Reason(in.Reason),
+	}
+
+	return resp
+}

tfprotov5/internal/toproto/deferred_test.go

@@ -0,0 +1,84 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package toproto_test
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5/internal/tfplugin5"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5/internal/toproto"
+)
+
+func TestDeferred(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		in       *tfprotov5.Deferred
+		expected *tfplugin5.Deferred
+	}{
+		"nil": {
+			in:       nil,
+			expected: nil,
+		},
+		"zero": {
+			in: &tfprotov5.Deferred{},
+			expected: &tfplugin5.Deferred{
+				Reason: tfplugin5.Deferred_UNKNOWN,
+			},
+		},
+		"Reason-ResourceConfigUnknown": {
+			in: &tfprotov5.Deferred{
+				Reason: tfprotov5.DeferredReasonResourceConfigUnknown,
+			},
+
+			expected: &tfplugin5.Deferred{
+				Reason: tfplugin5.Deferred_RESOURCE_CONFIG_UNKNOWN,
+			},
+		},
+		"Reason-ProviderConfigUnknown": {
+			in: &tfprotov5.Deferred{
+				Reason: tfprotov5.DeferredReasonProviderConfigUnknown,
+			},
+
+			expected: &tfplugin5.Deferred{
+				Reason: tfplugin5.Deferred_PROVIDER_CONFIG_UNKNOWN,
+			},
+		},
+		"Reason-AbsentPrereq": {
+			in: &tfprotov5.Deferred{
+				Reason: tfprotov5.DeferredReasonAbsentPrereq,
+			},
+
+			expected: &tfplugin5.Deferred{
+				Reason: tfplugin5.Deferred_ABSENT_PREREQ,
+			},
+		},
+	}
+
+	for name, testCase := range testCases {
+		name, testCase := name, testCase
+
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got := toproto.Deferred(testCase.in)
+
+			// Protocol Buffers generated types must have unexported fields
+			// ignored or cmp.Diff() will raise an error. This is easier than
+			// writing a custom Comparer for each type, which would have no
+			// benefits.
+			diffOpts := cmpopts.IgnoreUnexported(
+				tfplugin5.Deferred{},
+			)
+
+			if diff := cmp.Diff(got, testCase.expected, diffOpts); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}

tfprotov5/internal/toproto/resource.go

@@ -54,6 +54,7 @@ func ReadResource_Response(in *tfprotov5.ReadResourceResponse) *tfplugin5.ReadRe
 		Diagnostics: Diagnostics(in.Diagnostics),
 		NewState:    DynamicValue(in.NewState),
 		Private:     in.Private,
+		Deferred:    Deferred(in.Deferred),
 	}
 
 	return resp
@@ -70,6 +71,7 @@ func PlanResourceChange_Response(in *tfprotov5.PlanResourceChangeResponse) *tfpl
 		PlannedPrivate:   in.PlannedPrivate,
 		PlannedState:     DynamicValue(in.PlannedState),
 		RequiresReplace:  AttributePaths(in.RequiresReplace),
+		Deferred:         Deferred(in.Deferred),
 	}
 
 	return resp
@@ -98,6 +100,7 @@ func ImportResourceState_Response(in *tfprotov5.ImportResourceStateResponse) *tf
 	resp := &tfplugin5.ImportResourceState_Response{
 		Diagnostics:       Diagnostics(in.Diagnostics),
 		ImportedResources: ImportResourceState_ImportedResources(in.ImportedResources),
+		Deferred:          Deferred(in.Deferred),
 	}
 
 	return resp