Add a tfsdk.ConvertValue helper. (#120)

This function converts an `attr.Value` to use a new `attr.Type`, so long
as they share a compatible `tftypes.Type` representation. This allows
code that doesn't know the type of an `attr.Value` to still use it,
provided they know the kind of data it holds.

For example, a validation helper that works on strings--MaxStringLength,
say--could look something like this:

```
// assume req.Config is an attr.Value
strAttr, err := tfsdk.ConvertValue(ctx, req.Config, types.StringType)
if err != nil {
  panic(err)
}
var str types.String
diags := tfsdk.ValueAs(ctx, strAttr, &str)
if diags.HasError() {
  panic("oops")
}
// do something with `str`, which is now strongly typed
```

Then no matter what `attr.Type` provider devs use in their schema, this
validator would still work, then. Without the conversion step, it
wouldn't work, as `tfsdk.ValueAs` implementation needs to know the
`attr.Type` of the `attr.Value`, and reusable validators _can't_ know
that. So the point of this helper is to get an `attr.Value` into a known
`attr.Type` format.

Author: paddycarver

.changelog/120.txt

@@ -0,0 +1,7 @@
+```release-note:breaking-change
+`attr.Type` implementations must now have a `String()` method that returns a human-friendly name for the type.
+```
+
+```release-note:enhancement
+Added a `tfsdk.ConvertValue` helper that will convert any `attr.Value` into any compatible `attr.Type`. Compatibility happens at the terraform-plugin-go level; the type that the `attr.Value`'s `ToTerraformValue` method produces must be compatible with the `attr.Type`'s `TerraformType()`. Generally, this means that the `attr.Type` of the `attr.Value` and the `attr.Type` being converted to must both produce the same `tftypes.Type` when their `TerraformType()` method is called.
+```

attr/type.go

@@ -27,6 +27,9 @@ type Type interface {
 	// to the Type passed as an argument.
 	Equal(Type) bool
 
+	// String should return a human-friendly version of the Type.
+	String() string
+
 	tftypes.AttributePathStepper
 }
 

tfsdk/convert.go

@@ -0,0 +1,37 @@
+package tfsdk
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hashicorp/terraform-plugin-framework/attr"
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+)
+
+// ConvertValue creates a new attr.Value of the attr.Type `typ`, using the data
+// in `val`, which can be of any attr.Type so long as its TerraformType method
+// returns a tftypes.Type that `typ`'s ValueFromTerraform method can accept.
+func ConvertValue(ctx context.Context, val attr.Value, typ attr.Type) (attr.Value, diag.Diagnostics) {
+	tftype := typ.TerraformType(ctx)
+	tfval, err := val.ToTerraformValue(ctx)
+	if err != nil {
+		return nil, diag.Diagnostics{diag.NewErrorDiagnostic("Error converting value",
+			fmt.Sprintf("An unexpected error was encountered converting a %T to a %s. This is always a problem with the provider. Please tell the provider developers that %T ran into the following error during ToTerraformValue: %s", val, typ, val, err),
+		)}
+	}
+	err = tftypes.ValidateValue(tftype, tfval)
+	if err != nil {
+		return nil, diag.Diagnostics{diag.NewErrorDiagnostic("Error converting value",
+			fmt.Sprintf("An unexpected error was encountered converting a %T to a %s. This is always a problem with the provider. Please tell the provider developers that %T is not compatible with %s.", val, typ, val, typ),
+		)}
+	}
+	newVal := tftypes.NewValue(tftype, tfval)
+	res, err := typ.ValueFromTerraform(ctx, newVal)
+	if err != nil {
+		return nil, diag.Diagnostics{diag.NewErrorDiagnostic("Error converting value",
+			fmt.Sprintf("An unexpected error was encountered converting a %T to a %s. This is always a problem with the provider. Please tell the provider developers that %s returned the following error when calling ValueFromTerraform: %s", val, typ, typ, err),
+		)}
+	}
+	return res, nil
+}

tfsdk/convert_test.go

@@ -0,0 +1,71 @@
+package tfsdk
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/terraform-plugin-framework/attr"
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	testtypes "github.com/hashicorp/terraform-plugin-framework/internal/testing/types"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+func TestConvert(t *testing.T) {
+	t.Parallel()
+
+	type testCase struct {
+		val           attr.Value
+		typ           attr.Type
+		expected      attr.Value
+		expectedDiags diag.Diagnostics
+	}
+
+	tests := map[string]testCase{
+		"string-to-testtype-string": {
+			val: types.String{Value: "hello"},
+			typ: testtypes.StringType{},
+			expected: testtypes.String{
+				String:    types.String{Value: "hello"},
+				CreatedBy: testtypes.StringType{},
+			},
+		},
+		"testtype-string-to-string": {
+			val: testtypes.String{
+				String:    types.String{Value: "hello"},
+				CreatedBy: testtypes.StringType{},
+			},
+			typ:      types.StringType,
+			expected: types.String{Value: "hello"},
+		},
+		"string-to-number": {
+			val: types.String{Value: "hello"},
+			typ: types.NumberType,
+			expectedDiags: diag.Diagnostics{diag.NewErrorDiagnostic(
+				"Error converting value",
+				"An unexpected error was encountered converting a types.String to a types.NumberType. This is always a problem with the provider. Please tell the provider developers that types.String is not compatible with types.NumberType.",
+			)},
+		},
+	}
+
+	for name, tc := range tests {
+		name, tc := name, tc
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got, diags := ConvertValue(context.Background(), tc.val, tc.typ)
+
+			if diff := cmp.Diff(diags, tc.expectedDiags); diff != "" {
+				t.Fatalf("Unexpected diff in diags (-wanted, +got): %s", diff)
+			}
+
+			if diags.HasError() {
+				return
+			}
+
+			if diff := cmp.Diff(got, tc.expected); diff != "" {
+				t.Fatalf("Unexpected diff in result (-wanted, +got): %s", diff)
+			}
+		})
+	}
+}

types/list.go

@@ -101,6 +101,11 @@ func (l ListType) ApplyTerraform5AttributePathStep(step tftypes.AttributePathSte
 	return l.ElemType, nil
 }
 
+// String returns a human-friendly description of the ListType.
+func (l ListType) String() string {
+	return "types.ListType[" + l.ElemType.String() + "]"
+}
+
 // List represents a list of AttributeValues, all of the same type, indicated
 // by ElemType.
 type List struct {

types/map.go

@@ -99,6 +99,11 @@ func (m MapType) ApplyTerraform5AttributePathStep(step tftypes.AttributePathStep
 	return m.ElemType, nil
 }
 
+// String returns a human-friendly description of the MapType.
+func (m MapType) String() string {
+	return "types.MapType[" + m.ElemType.String() + "]"
+}
+
 // Map represents a map of AttributeValues, all of the same type, indicated by
 // ElemType. Keys for the map will always be strings.
 type Map struct {

types/object.go

@@ -3,6 +3,8 @@ package types
 import (
 	"context"
 	"fmt"
+	"sort"
+	"strings"
 
 	"github.com/hashicorp/terraform-plugin-framework/attr"
 	"github.com/hashicorp/terraform-plugin-framework/diag"
@@ -112,6 +114,26 @@ func (o ObjectType) ApplyTerraform5AttributePathStep(step tftypes.AttributePathS
 	return o.AttrTypes[string(step.(tftypes.AttributeName))], nil
 }
 
+// String returns a human-friendly description of the ObjectType.
+func (o ObjectType) String() string {
+	var res strings.Builder
+	res.WriteString("types.ObjectType[")
+	keys := make([]string, 0, len(o.AttrTypes))
+	for k := range o.AttrTypes {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	for pos, key := range keys {
+		if pos != 0 {
+			res.WriteString(", ")
+		}
+		res.WriteString(`"` + key + `":`)
+		res.WriteString(o.AttrTypes[key].String())
+	}
+	res.WriteString("]")
+	return res.String()
+}
+
 // Object represents an object
 type Object struct {
 	// Unknown will be set to true if the entire object is an unknown value.

types/primitive_test.go

@@ -71,6 +71,11 @@ func (t testAttributeType) ApplyTerraform5AttributePathStep(_ tftypes.AttributeP
 	panic("not implemented")
 }
 
+// String should return a human-friendly version of the Type.
+func (t testAttributeType) String() string {
+	panic("not implemented")
+}
+
 func TestPrimitiveEqual(t *testing.T) {
 	t.Parallel()