remove state from renew/close, add deferred action support

Author: austinvalle

ephemeral/close.go

@@ -5,17 +5,12 @@ package ephemeral
 import (
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/privatestate"
-	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
 )
 
 // CloseRequest represents a request for the provider to close an ephemeral
 // resource. An instance of this request struct is supplied as an argument to
 // the ephemeral resource's Close function.
 type CloseRequest struct {
-	// State is the object representing the values of the ephemeral
-	// resource following the Open operation.
-	State tfsdk.EphemeralState
-
 	// Private is provider-defined ephemeral resource private state data
 	// which was previously provided by the latest Open or Renew operation.
 	//

ephemeral/deferred.go

@@ -0,0 +1,50 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package ephemeral
+
+const (
+	// DeferredReasonUnknown is used to indicate an invalid `DeferredReason`.
+	// Provider developers should not use it.
+	DeferredReasonUnknown DeferredReason = 0
+
+	// DeferredReasonEphemeralResourceConfigUnknown is used to indicate that the ephemeral resource configuration
+	// is partially unknown and the real values need to be known before the change can be planned.
+	DeferredReasonEphemeralResourceConfigUnknown 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
+)
+
+// Deferred is used to indicate to Terraform that a change needs to be deferred for a reason.
+//
+// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
+// to change or break without warning. It is not protected by version compatibility guarantees.
+type Deferred struct {
+	// Reason is the reason for deferring the change.
+	Reason DeferredReason
+}
+
+// DeferredReason represents different reasons for deferring a change.
+//
+// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
+// to change or break without warning. It is not protected by version compatibility guarantees.
+type DeferredReason int32
+
+func (d DeferredReason) String() string {
+	switch d {
+	case 0:
+		return "Unknown"
+	case 1:
+		return "Ephemeral Resource Config Unknown"
+	case 2:
+		return "Provider Config Unknown"
+	case 3:
+		return "Absent Prerequisite"
+	}
+	return "Unknown"
+}

ephemeral/open.go

@@ -10,25 +10,41 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
 )
 
+// OpenClientCapabilities allows Terraform to publish information
+// regarding optionally supported protocol features for the OpenEphemeralResource RPC,
+// such as forward-compatible Terraform behavior changes.
+type OpenClientCapabilities struct {
+	// DeferralAllowed indicates whether the Terraform client initiating
+	// the request allows a deferral response.
+	//
+	// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
+	// to change or break without warning. It is not protected by version compatibility guarantees.
+	DeferralAllowed bool
+}
+
 // OpenRequest represents a request for the provider to open an ephemeral
 // resource. An instance of this request struct is supplied as an argument to
 // the ephemeral resource's Open function.
 type OpenRequest struct {
 	// Config is the configuration the user supplied for the ephemeral
 	// resource.
 	Config tfsdk.Config
+
+	// ClientCapabilities defines optionally supported protocol features for the
+	// OpenEphemeralResource RPC, such as forward-compatible Terraform behavior changes.
+	ClientCapabilities OpenClientCapabilities
 }
 
 // OpenResponse represents a response to a OpenRequest. An
 // instance of this response struct is supplied as an argument
 // to the ephemeral resource's Open function, in which the provider
 // should set values on the OpenResponse as appropriate.
 type OpenResponse struct {
-	// State is the object representing the values of the ephemeral
+	// Result is the object representing the values of the ephemeral
 	// resource following the Open operation. This field is pre-populated
 	// from OpenRequest.Config and should be set during the resource's Open
 	// operation.
-	State tfsdk.EphemeralState
+	Result tfsdk.EphemeralResultData
 
 	// Private is the private state ephemeral resource data following the
 	// Open operation. This field is not pre-populated as there is no
@@ -50,4 +66,14 @@ type OpenResponse struct {
 	// resource. An empty slice indicates a successful operation with no
 	// warnings or errors generated.
 	Diagnostics diag.Diagnostics
+
+	// Deferred indicates that Terraform should defer opening this
+	// ephemeral resource until a followup apply operation.
+	//
+	// This field can only be set if
+	// `(ephemeral.OpenRequest).ClientCapabilities.DeferralAllowed` is true.
+	//
+	// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
+	// to change or break without warning. It is not protected by version compatibility guarantees.
+	Deferred *Deferred
 }

ephemeral/renew.go

@@ -7,17 +7,12 @@ import (
 
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/internal/privatestate"
-	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
 )
 
 // RenewRequest represents a request for the provider to renew an ephemeral
 // resource. An instance of this request struct is supplied as an argument to
 // the ephemeral resource's Renew function.
 type RenewRequest struct {
-	// State is the object representing the values of the ephemeral
-	// resource following the Open operation.
-	State tfsdk.EphemeralState
-
 	// Private is provider-defined ephemeral resource private state data
 	// which was previously provided by the latest Open or Renew operation.
 	// Any existing data is copied to RenewResponse.Private to prevent

go.mod

@@ -6,7 +6,7 @@ toolchain go1.22.7
 
 require (
 	github.com/google/go-cmp v0.6.0
-	github.com/hashicorp/terraform-plugin-go v0.24.1-0.20240924154457-cd3b6654adf0
+	github.com/hashicorp/terraform-plugin-go v0.24.1-0.20241003195015-94a6f8ce9ce7
 	github.com/hashicorp/terraform-plugin-log v0.9.0
 )
 
@@ -29,6 +29,6 @@ require (
 	golang.org/x/sys v0.24.0 // indirect
 	golang.org/x/text v0.17.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240814211410-ddb44dafa142 // indirect
-	google.golang.org/grpc v1.67.0 // indirect
+	google.golang.org/grpc v1.67.1 // indirect
 	google.golang.org/protobuf v1.34.2 // indirect
 )

go.sum

@@ -15,8 +15,8 @@ github.com/hashicorp/go-plugin v1.6.1 h1:P7MR2UP6gNKGPp+y7EZw2kOiq4IR9WiqLvp0XOs
 github.com/hashicorp/go-plugin v1.6.1/go.mod h1:XPHFku2tFo3o3QKFgSYo+cghcUhw1NA1hZyMK0PWAw0=
 github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8=
 github.com/hashicorp/go-uuid v1.0.3/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
-github.com/hashicorp/terraform-plugin-go v0.24.1-0.20240924154457-cd3b6654adf0 h1:WgAlLzllo3v6BeZccPW5IETHgRylr/9y37X314C+09I=
-github.com/hashicorp/terraform-plugin-go v0.24.1-0.20240924154457-cd3b6654adf0/go.mod h1:zoSM9LyEFI4iVkDeKXgwBHV0uTuIIXydtK1fy9J4wBA=
+github.com/hashicorp/terraform-plugin-go v0.24.1-0.20241003195015-94a6f8ce9ce7 h1:Qrnz5z9gKKn7oDhWNKPLzl7yygiz322p1Rkzx5uqLiA=
+github.com/hashicorp/terraform-plugin-go v0.24.1-0.20241003195015-94a6f8ce9ce7/go.mod h1:lmP6B7frH0MrScpBN0x9kY8DSFSUWX54NmeL00knT9c=
 github.com/hashicorp/terraform-plugin-log v0.9.0 h1:i7hOA+vdAItN1/7UrfBqBwvYPQ9TFvymaRGZED3FCV0=
 github.com/hashicorp/terraform-plugin-log v0.9.0/go.mod h1:rKL8egZQ/eXSyDqzLUuwUYLVdlYeamldAHSxjUFADow=
 github.com/hashicorp/terraform-registry-address v0.2.3 h1:2TAiKJ1A3MAkZlH1YI/aTVcLZRu7JseiXNRHbOAyoTI=
@@ -59,8 +59,8 @@ golang.org/x/text v0.17.0 h1:XtiM5bkSOt+ewxlOE/aE/AKEHibwj/6gvWMl9Rsh0Qc=
 golang.org/x/text v0.17.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20240814211410-ddb44dafa142 h1:e7S5W7MGGLaSu8j3YjdezkZ+m1/Nm0uRVRMEMGk26Xs=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20240814211410-ddb44dafa142/go.mod h1:UqMtugtsSgubUsoxbuAoiCXvqvErP7Gf0so0mK9tHxU=
-google.golang.org/grpc v1.67.0 h1:IdH9y6PF5MPSdAntIcpjQ+tXO41pcQsfZV2RxtQgVcw=
-google.golang.org/grpc v1.67.0/go.mod h1:1gLDyUQU7CTLJI90u3nXZ9ekeghjeM7pTDZlqFNg2AA=
+google.golang.org/grpc v1.67.1 h1:zWnc1Vrcno+lHZCOofnIMvycFcc0QRGIzm9dhnDX68E=
+google.golang.org/grpc v1.67.1/go.mod h1:1gLDyUQU7CTLJI90u3nXZ9ekeghjeM7pTDZlqFNg2AA=
 google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg=
 google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/fromproto5/client_capabilities.go

@@ -7,6 +7,7 @@ import (
 	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
 
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/ephemeral"
 	"github.com/hashicorp/terraform-plugin-framework/provider"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 )
@@ -75,3 +76,16 @@ func ImportStateClientCapabilities(in *tfprotov5.ImportResourceStateClientCapabi
 		DeferralAllowed: in.DeferralAllowed,
 	}
 }
+
+func OpenEphemeralResourceClientCapabilities(in *tfprotov5.OpenEphemeralResourceClientCapabilities) ephemeral.OpenClientCapabilities {
+	if in == nil {
+		// Client did not indicate any supported capabilities
+		return ephemeral.OpenClientCapabilities{
+			DeferralAllowed: false,
+		}
+	}
+
+	return ephemeral.OpenClientCapabilities{
+		DeferralAllowed: in.DeferralAllowed,
+	}
+}

internal/fromproto5/closeephemeralresource.go

@@ -42,12 +42,6 @@ func CloseEphemeralResourceRequest(ctx context.Context, proto5 *tfprotov5.CloseE
 		EphemeralResourceSchema: ephemeralResourceSchema,
 	}
 
-	state, stateDiags := EphemeralState(ctx, proto5.State, ephemeralResourceSchema)
-
-	diags.Append(stateDiags...)
-
-	fw.State = state
-
 	privateData, privateDataDiags := privatestate.NewData(ctx, proto5.Private)
 
 	diags.Append(privateDataDiags...)

internal/fromproto5/closeephemeralresource_test.go

@@ -9,7 +9,6 @@ import (
 
 	"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/ephemeral"
@@ -18,28 +17,11 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
 	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
 	"github.com/hashicorp/terraform-plugin-framework/internal/privatestate"
-	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
 )
 
 func TestCloseEphemeralResourceRequest(t *testing.T) {
 	t.Parallel()
 
-	testProto5Type := tftypes.Object{
-		AttributeTypes: map[string]tftypes.Type{
-			"test_attribute": tftypes.String,
-		},
-	}
-
-	testProto5Value := tftypes.NewValue(testProto5Type, map[string]tftypes.Value{
-		"test_attribute": tftypes.NewValue(tftypes.String, "test-value"),
-	})
-
-	testProto5DynamicValue, err := tfprotov5.NewDynamicValue(testProto5Type, testProto5Value)
-
-	if err != nil {
-		t.Fatalf("unexpected error calling tfprotov5.NewDynamicValue(): %s", err)
-	}
-
 	testFwSchema := schema.Schema{
 		Attributes: map[string]schema.Attribute{
 			"test_attribute": schema.StringAttribute{
@@ -97,34 +79,6 @@ func TestCloseEphemeralResourceRequest(t *testing.T) {
 				EphemeralResourceSchema: testFwSchema,
 			},
 		},
-		"state-missing-schema": {
-			input: &tfprotov5.CloseEphemeralResourceRequest{
-				State: &testProto5DynamicValue,
-			},
-			expected: nil,
-			expectedDiagnostics: diag.Diagnostics{
-				diag.NewErrorDiagnostic(
-					"Missing EphemeralResource Schema",
-					"An unexpected error was encountered when handling the request. "+
-						"This is always an issue in terraform-plugin-framework used to implement the provider and should be reported to the provider developers.\n\n"+
-						"Please report this to the provider developer:\n\n"+
-						"Missing schema.",
-				),
-			},
-		},
-		"state": {
-			input: &tfprotov5.CloseEphemeralResourceRequest{
-				State: &testProto5DynamicValue,
-			},
-			ephemeralResourceSchema: testFwSchema,
-			expected: &fwserver.CloseEphemeralResourceRequest{
-				State: &tfsdk.EphemeralState{
-					Raw:    testProto5Value,
-					Schema: testFwSchema,
-				},
-				EphemeralResourceSchema: testFwSchema,
-			},
-		},
 	}
 
 	for name, testCase := range testCases {

internal/fromproto5/ephemeral_state.go renamed to internal/fromproto5/ephemeral_result_data.go

@@ -13,9 +13,9 @@ import (
 	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
 )
 
-// EphemeralState returns the *tfsdk.EphemeralState for a *tfprotov5.DynamicValue and
+// EphemeralResultData returns the *tfsdk.EphemeralResultData for a *tfprotov5.DynamicValue and
 // fwschema.Schema.
-func EphemeralState(ctx context.Context, proto5DynamicValue *tfprotov5.DynamicValue, schema fwschema.Schema) (*tfsdk.EphemeralState, diag.Diagnostics) {
+func EphemeralResultData(ctx context.Context, proto5DynamicValue *tfprotov5.DynamicValue, schema fwschema.Schema) (*tfsdk.EphemeralResultData, diag.Diagnostics) {
 	if proto5DynamicValue == nil {
 		return nil, nil
 	}
@@ -26,8 +26,8 @@ func EphemeralState(ctx context.Context, proto5DynamicValue *tfprotov5.DynamicVa
 	// This should not happen, but just in case.
 	if schema == nil {
 		diags.AddError(
-			"Unable to Convert Ephemeral State",
-			"An unexpected error was encountered when converting the ephemeral state from the protocol type. "+
+			"Unable to Convert Ephemeral Result Data",
+			"An unexpected error was encountered when converting the ephemeral result data from the protocol type. "+
 				"This is always an issue in terraform-plugin-framework used to implement the provider and should be reported to the provider developers.\n\n"+
 				"Please report this to the provider developer:\n\n"+
 				"Missing schema.",
@@ -36,15 +36,15 @@ func EphemeralState(ctx context.Context, proto5DynamicValue *tfprotov5.DynamicVa
 		return nil, diags
 	}
 
-	data, dynamicValueDiags := DynamicValue(ctx, proto5DynamicValue, schema, fwschemadata.DataDescriptionEphemeralState)
+	data, dynamicValueDiags := DynamicValue(ctx, proto5DynamicValue, schema, fwschemadata.DataDescriptionEphemeralResultData)
 
 	diags.Append(dynamicValueDiags...)
 
 	if diags.HasError() {
 		return nil, diags
 	}
 
-	fw := &tfsdk.EphemeralState{
+	fw := &tfsdk.EphemeralResultData{
 		Raw:    data.TerraformValue,
 		Schema: schema,
 	}