action: Implement planning and invoking of actions

action/action.go

@@ -12,5 +12,40 @@ type Action interface {
 	// Metadata should return the full name of the action, such as examplecloud_do_thing.
 	Metadata(context.Context, MetadataRequest, *MetadataResponse)
 
-	// TODO:Actions: Eventual landing place for all required methods to implement for an action
+	// Invoke is called to run the logic of the action and update linked resources if applicable.
+	// Config, linked resource planned state, and linked resource prior state values should
+	// be read from the InvokeRequest and new linked resource state values set on the InvokeResponse.
+	//
+	// The [InvokeResponse.SendProgress] function can be called in the Invoke method to immediately
+	// report progress events related to the invocation of the action to Terraform.
+	Invoke(context.Context, InvokeRequest, *InvokeResponse)
+}
+
+// ActionWithConfigure is an interface type that extends Action to
+// include a method which the framework will automatically call so provider
+// developers have the opportunity to setup any necessary provider-level data
+// or clients in the Action type.
+type ActionWithConfigure interface {
+	Action
+
+	// Configure enables provider-level data or clients to be set in the
+	// provider-defined Action type.
+	Configure(context.Context, ConfigureRequest, *ConfigureResponse)
+}
+
+// ActionWithModifyPlan represents an action with a ModifyPlan function.
+type ActionWithModifyPlan interface {
+	Action
+
+	// ModifyPlan is called when the provider has an opportunity to modify
+	// the plan for an action: once during the plan phase, and once
+	// during the apply phase with any unknown values from configuration
+	// filled in with their final values.
+	//
+	// Actions do not have computed attributes that can be modified during the plan,
+	// but linked and lifecycle actions can modify the plan of linked resources.
+	//
+	// All action schema types can use the plan as an opportunity to raise early
+	// diagnostics to practitioners, such as validation errors.
+	ModifyPlan(context.Context, ModifyPlanRequest, *ModifyPlanResponse)
 }

action/configure.go

@@ -0,0 +1,32 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package action
+
+import "github.com/hashicorp/terraform-plugin-framework/diag"
+
+// ConfigureRequest represents a request for the provider to configure an
+// action, i.e., set provider-level data or clients. An instance of this
+// request struct is supplied as an argument to the Action type Configure
+// method.
+type ConfigureRequest struct {
+	// ProviderData is the data set in the
+	// [provider.ConfigureResponse.ActionData] field. This data is
+	// provider-specifc and therefore can contain any necessary remote system
+	// clients, custom provider data, or anything else pertinent to the
+	// functionality of the Action.
+	//
+	// This data is only set after the ConfigureProvider RPC has been called
+	// by Terraform.
+	ProviderData any
+}
+
+// ConfigureResponse represents a response to a ConfigureRequest. An
+// instance of this response struct is supplied as an argument to the
+// Action type Configure method.
+type ConfigureResponse struct {
+	// Diagnostics report errors or warnings related to configuring of the
+	// Datasource. An empty slice indicates a successful operation with no
+	// warnings or errors generated.
+	Diagnostics diag.Diagnostics
+}

action/deferred.go

@@ -0,0 +1,50 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package action
+
+const (
+	// DeferredReasonUnknown is used to indicate an invalid `DeferredReason`.
+	// Provider developers should not use it.
+	DeferredReasonUnknown DeferredReason = 0
+
+	// DeferredReasonActionConfigUnknown is used to indicate that the action configuration
+	// is partially unknown and the real values need to be known before the change can be planned.
+	DeferredReasonActionConfigUnknown 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 "Action Config Unknown"
+	case 2:
+		return "Provider Config Unknown"
+	case 3:
+		return "Absent Prerequisite"
+	}
+	return "Unknown"
+}

action/invoke.go

@@ -0,0 +1,45 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package action
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
+)
+
+// InvokeRequest represents a request for the provider to invoke the action and update
+// the requested action's linked resources.
+type InvokeRequest struct {
+	// Config is the configuration the user supplied for the action.
+	Config tfsdk.Config
+
+	// TODO:Actions: Add linked resources once lifecycle/linked actions are implemented
+}
+
+// InvokeResponse represents a response to an InvokeRequest. An
+// instance of this response struct is supplied as
+// an argument to the action's Invoke function, in which the provider
+// should set values on the InvokeResponse as appropriate.
+type InvokeResponse struct {
+	// Diagnostics report errors or warnings related to invoking the action or updating
+	// the state of the requested action's linked resources. Returning an empty slice
+	// indicates a successful invocation with no warnings or errors
+	// generated.
+	Diagnostics diag.Diagnostics
+
+	// SendProgress will immediately send a progress update to Terraform core during action invocation.
+	// This function is provided by the framework and can be called multiple times while action logic is running.
+	//
+	// TODO:Actions: More documentation about when you should use this / when you shouldn't
+	SendProgress func(event InvokeProgressEvent)
+
+	// TODO:Actions: Add linked resources once lifecycle/linked actions are implemented
+}
+
+// InvokeProgressEvent is the event returned to Terraform while an action is being invoked.
+type InvokeProgressEvent struct {
+	// Message is the string that will be presented to the practitioner either via the console
+	// or an external system like HCP Terraform.
+	Message string
+}

action/modify_plan.go

@@ -0,0 +1,62 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package action
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
+)
+
+// ModifyPlanClientCapabilities allows Terraform to publish information
+// regarding optionally supported protocol features for the PlanAction RPC,
+// such as forward-compatible Terraform behavior changes.
+type ModifyPlanClientCapabilities 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
+}
+
+// ModifyPlanRequest represents a request for the provider to modify the
+// planned new state that Terraform has generated for any linked resources.
+type ModifyPlanRequest struct {
+	// Config is the configuration the user supplied for the action.
+	//
+	// This configuration may contain unknown values if a user uses
+	// interpolation or other functionality that would prevent Terraform
+	// from knowing the value at request time.
+	Config tfsdk.Config
+
+	// TODO:Actions: Add linked resources once lifecycle/linked actions are implemented
+
+	// ClientCapabilities defines optionally supported protocol features for the
+	// PlanAction RPC, such as forward-compatible Terraform behavior changes.
+	ClientCapabilities ModifyPlanClientCapabilities
+}
+
+// ModifyPlanResponse represents a response to a
+// ModifyPlanRequest. An instance of this response struct is supplied
+// as an argument to the action's ModifyPlan function, in which the provider
+// should modify the Plan of any linked resources as appropriate.
+type ModifyPlanResponse struct {
+	// Diagnostics report errors or warnings related to determining the
+	// planned state of the requested action's linked resources. Returning an empty slice
+	// indicates a successful plan modification with no warnings or errors
+	// generated.
+	Diagnostics diag.Diagnostics
+
+	// TODO:Actions: Add linked resources once lifecycle/linked actions are implemented
+
+	// Deferred indicates that Terraform should defer planning this
+	// action until a follow-up apply operation.
+	//
+	// This field can only be set if
+	// `(action.ModifyPlanRequest).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
+}

internal/fromproto5/client_capabilities.go

@@ -6,6 +6,7 @@ package fromproto5
 import (
 	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
 
+	"github.com/hashicorp/terraform-plugin-framework/action"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/ephemeral"
 	"github.com/hashicorp/terraform-plugin-framework/provider"
@@ -102,3 +103,16 @@ func ValidateResourceTypeConfigClientCapabilities(in *tfprotov5.ValidateResource
 		WriteOnlyAttributesAllowed: in.WriteOnlyAttributesAllowed,
 	}
 }
+
+func ModifyPlanActionClientCapabilities(in *tfprotov5.PlanActionClientCapabilities) action.ModifyPlanClientCapabilities {
+	if in == nil {
+		// Client did not indicate any supported capabilities
+		return action.ModifyPlanClientCapabilities{
+			DeferralAllowed: false,
+		}
+	}
+
+	return action.ModifyPlanClientCapabilities{
+		DeferralAllowed: in.DeferralAllowed,
+	}
+}

internal/fromproto5/invokeaction.go

@@ -37,6 +37,7 @@ func InvokeActionRequest(ctx context.Context, proto5 *tfprotov5.InvokeActionRequ
 	}
 
 	fw := &fwserver.InvokeActionRequest{
+		Action:       reqAction,
 		ActionSchema: actionSchema,
 	}
 

internal/fromproto5/invokeaction_test.go

@@ -3,4 +3,118 @@
 
 package fromproto5_test
 
-// TODO:Actions: Add unit tests once this mapping logic is complete
+import (
+	"context"
+	"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/action"
+	"github.com/hashicorp/terraform-plugin-framework/action/schema"
+	"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/internal/fwserver"
+	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
+)
+
+func TestInvokeActionRequest(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)
+	}
+
+	testUnlinkedSchema := schema.UnlinkedSchema{
+		Attributes: map[string]schema.Attribute{
+			"test_attribute": schema.StringAttribute{
+				Required: true,
+			},
+		},
+	}
+
+	testCases := map[string]struct {
+		input               *tfprotov5.InvokeActionRequest
+		actionSchema        fwschema.Schema
+		actionImpl          action.Action
+		providerMetaSchema  fwschema.Schema
+		expected            *fwserver.InvokeActionRequest
+		expectedDiagnostics diag.Diagnostics
+	}{
+		"nil": {
+			input:    nil,
+			expected: nil,
+		},
+		"empty": {
+			input:    &tfprotov5.InvokeActionRequest{},
+			expected: nil,
+			expectedDiagnostics: diag.Diagnostics{
+				diag.NewErrorDiagnostic(
+					"Missing Action 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.",
+				),
+			},
+		},
+		"config-missing-schema": {
+			input: &tfprotov5.InvokeActionRequest{
+				Config: &testProto5DynamicValue,
+			},
+			expected: nil,
+			expectedDiagnostics: diag.Diagnostics{
+				diag.NewErrorDiagnostic(
+					"Missing Action 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.",
+				),
+			},
+		},
+		"config": {
+			input: &tfprotov5.InvokeActionRequest{
+				Config: &testProto5DynamicValue,
+			},
+			actionSchema: testUnlinkedSchema,
+			expected: &fwserver.InvokeActionRequest{
+				Config: &tfsdk.Config{
+					Raw:    testProto5Value,
+					Schema: testUnlinkedSchema,
+				},
+				ActionSchema: testUnlinkedSchema,
+			},
+		},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got, diags := fromproto5.InvokeActionRequest(context.Background(), testCase.input, testCase.actionImpl, testCase.actionSchema)
+
+			if diff := cmp.Diff(got, testCase.expected); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+
+			if diff := cmp.Diff(diags, testCase.expectedDiagnostics); diff != "" {
+				t.Errorf("unexpected diagnostics difference: %s", diff)
+			}
+		})
+	}
+}