protov5 and fwserver impl

Author: austinvalle

action/action.go

@@ -0,0 +1,16 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package action
+
+import "context"
+
+type Action interface {
+	// Schema should return the schema for this action.
+	Schema(context.Context, SchemaRequest, *SchemaResponse)
+
+	// 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
+}

action/doc.go

@@ -0,0 +1,5 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+// TODO:Actions: Eventual package docs for actions
+package action

action/metadata.go

@@ -0,0 +1,24 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package action
+
+// MetadataRequest represents a request for the Action to return metadata,
+// such as its type name. An instance of this request struct is supplied as
+// an argument to the Action type Metadata method.
+type MetadataRequest struct {
+	// ProviderTypeName is the string returned from
+	// [provider.MetadataResponse.TypeName], if the Provider type implements
+	// the Metadata method. This string should prefix the Action type name
+	// with an underscore in the response.
+	ProviderTypeName string
+}
+
+// MetadataResponse represents a response to a MetadataRequest. An
+// instance of this response struct is supplied as an argument to the
+// Action type Metadata method.
+type MetadataResponse struct {
+	// TypeName should be the full action type, including the provider
+	// type prefix and an underscore. For example, examplecloud_thing.
+	TypeName string
+}

action/schema.go

@@ -0,0 +1,28 @@
+// 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/internal/fwschema"
+)
+
+// SchemaRequest represents a request for the Action to return its schema.
+// An instance of this request struct is supplied as an argument to the
+// Action type Schema method.
+type SchemaRequest struct{}
+
+// SchemaResponse represents a response to a SchemaRequest. An instance of this
+// response struct is supplied as an argument to the Action type Schema
+// method.
+type SchemaResponse struct {
+	// TODO:Actions: This will eventually be replaced by an interface defined in
+	// an "actions/schema" package. Schema implementations that will fulfill this
+	// interface will be unlinked, linked, or lifecycle. (also defined in the "actions/schema" package)
+	Schema fwschema.Schema
+
+	// Diagnostics report errors or warnings related to retrieving the action schema.
+	// An empty slice indicates success, with no warnings or errors generated.
+	Diagnostics diag.Diagnostics
+}

internal/fromproto5/invokeaction.go

@@ -0,0 +1,52 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package fromproto5
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+
+	"github.com/hashicorp/terraform-plugin-framework/action"
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
+)
+
+// InvokeActionRequest returns the *fwserver.InvokeActionRequest equivalent of a *tfprotov5.InvokeActionRequest.
+func InvokeActionRequest(ctx context.Context, proto5 *tfprotov5.InvokeActionRequest, reqAction action.Action, actionSchema fwschema.Schema) (*fwserver.InvokeActionRequest, diag.Diagnostics) {
+	if proto5 == nil {
+		return nil, nil
+	}
+
+	var diags diag.Diagnostics
+
+	// Panic prevention here to simplify the calling implementations.
+	// This should not happen, but just in case.
+	if actionSchema == nil {
+		diags.AddError(
+			"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.",
+		)
+
+		return nil, diags
+	}
+
+	fw := &fwserver.InvokeActionRequest{
+		ActionSchema: actionSchema,
+	}
+
+	config, configDiags := Config(ctx, proto5.Config, actionSchema)
+
+	diags.Append(configDiags...)
+
+	fw.Config = config
+
+	// TODO:Actions: Here we need to retrieve linked resource data
+
+	return fw, diags
+}

internal/fromproto5/invokeaction_test.go

@@ -0,0 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package fromproto5_test
+
+// TODO:Actions: Add unit tests once this mapping logic is complete

internal/fromproto5/planaction.go

@@ -0,0 +1,52 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package fromproto5
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+
+	"github.com/hashicorp/terraform-plugin-framework/action"
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
+)
+
+// PlanActionRequest returns the *fwserver.PlanActionRequest equivalent of a *tfprotov5.PlanActionRequest.
+func PlanActionRequest(ctx context.Context, proto5 *tfprotov5.PlanActionRequest, reqAction action.Action, actionSchema fwschema.Schema) (*fwserver.PlanActionRequest, diag.Diagnostics) {
+	if proto5 == nil {
+		return nil, nil
+	}
+
+	var diags diag.Diagnostics
+
+	// Panic prevention here to simplify the calling implementations.
+	// This should not happen, but just in case.
+	if actionSchema == nil {
+		diags.AddError(
+			"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.",
+		)
+
+		return nil, diags
+	}
+
+	fw := &fwserver.PlanActionRequest{
+		ActionSchema: actionSchema,
+	}
+
+	config, configDiags := Config(ctx, proto5.Config, actionSchema)
+
+	diags.Append(configDiags...)
+
+	fw.Config = config
+
+	// TODO:Actions: Here we need to retrieve client capabilities and linked resource data
+
+	return fw, diags
+}

internal/fromproto5/planaction_test.go

@@ -0,0 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package fromproto5_test
+
+// TODO:Actions: Add unit tests once this mapping logic is complete

internal/fwserver/server.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"sync"
 
+	"github.com/hashicorp/terraform-plugin-framework/action"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/ephemeral"
@@ -40,6 +41,29 @@ type Server struct {
 	// to [ephemeral.ConfigureRequest.ProviderData].
 	EphemeralResourceConfigureData any
 
+	// actionSchemas is the cached Action Schemas for RPCs that need to
+	// convert configuration data from the protocol. If not found, it will be
+	// fetched from the Action.Schema() method.
+	actionSchemas map[string]fwschema.Schema
+
+	// actionSchemasMutex is a mutex to protect concurrent actionSchemas
+	// access from race conditions.
+	actionSchemasMutex sync.RWMutex
+
+	// actionFuncs is the cached Action functions for RPCs that need to
+	// access actions. If not found, it will be fetched from the
+	// Provider.Actions() method.
+	actionFuncs map[string]func() action.Action
+
+	// actionFuncsDiags is the cached Diagnostics obtained while populating
+	// actionFuncs. This is to ensure any warnings or errors are also
+	// returned appropriately when fetching actionFuncs.
+	actionFuncsDiags diag.Diagnostics
+
+	// actionFuncsMutex is a mutex to protect concurrent actionFuncs
+	// access from race conditions.
+	actionFuncsMutex sync.Mutex
+
 	// dataSourceSchemas is the cached DataSource Schemas for RPCs that need to
 	// convert configuration data from the protocol. If not found, it will be
 	// fetched from the DataSourceType.GetSchema() method.

internal/fwserver/server_actions.go

@@ -0,0 +1,142 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package fwserver
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hashicorp/terraform-plugin-framework/action"
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwschema"
+	"github.com/hashicorp/terraform-plugin-framework/internal/logging"
+	"github.com/hashicorp/terraform-plugin-framework/provider"
+)
+
+// Action returns the Action for a given action type.
+func (s *Server) Action(ctx context.Context, actionType string) (action.Action, diag.Diagnostics) {
+	actionFuncs, diags := s.ActionFuncs(ctx)
+
+	actionFunc, ok := actionFuncs[actionType]
+
+	if !ok {
+		diags.AddError(
+			"Action Type Not Found",
+			fmt.Sprintf("No action type named %q was found in the provider.", actionType),
+		)
+
+		return nil, diags
+	}
+
+	return actionFunc(), diags
+}
+
+// ActionFuncs returns a map of Action functions. The results are cached
+// on first use.
+func (s *Server) ActionFuncs(ctx context.Context) (map[string]func() action.Action, diag.Diagnostics) {
+	logging.FrameworkTrace(ctx, "Checking ActionFuncs lock")
+	s.actionFuncsMutex.Lock()
+	defer s.actionFuncsMutex.Unlock()
+
+	if s.actionFuncs != nil {
+		return s.actionFuncs, s.actionFuncsDiags
+	}
+
+	providerTypeName := s.ProviderTypeName(ctx)
+	s.actionFuncs = make(map[string]func() action.Action)
+
+	provider, ok := s.Provider.(provider.ProviderWithActions)
+	if !ok {
+		// Only action specific RPCs should return diagnostics about the
+		// provider not implementing actions or missing actions.
+		return s.actionFuncs, s.actionFuncsDiags
+	}
+
+	logging.FrameworkTrace(ctx, "Calling provider defined Provider Actions")
+	actionFuncsSlice := provider.Actions(ctx)
+	logging.FrameworkTrace(ctx, "Called provider defined Provider Actions")
+
+	for _, actionFunc := range actionFuncsSlice {
+		actionImpl := actionFunc()
+
+		actionTypeReq := action.MetadataRequest{
+			ProviderTypeName: providerTypeName,
+		}
+		actionTypeResp := action.MetadataResponse{}
+
+		actionImpl.Metadata(ctx, actionTypeReq, &actionTypeResp)
+
+		if actionTypeResp.TypeName == "" {
+			s.actionFuncsDiags.AddError(
+				"Action Type Missing",
+				fmt.Sprintf("The %T Action returned an empty string from the Metadata method. ", actionImpl)+
+					"This is always an issue with the provider and should be reported to the provider developers.",
+			)
+			continue
+		}
+
+		logging.FrameworkTrace(ctx, "Found action", map[string]interface{}{logging.KeyActionType: actionTypeResp.TypeName})
+
+		if _, ok := s.actionFuncs[actionTypeResp.TypeName]; ok {
+			s.actionFuncsDiags.AddError(
+				"Duplicate Action Defined",
+				fmt.Sprintf("The %s action type was returned for multiple actions. ", actionTypeResp.TypeName)+
+					"Action types must be unique. "+
+					"This is always an issue with the provider and should be reported to the provider developers.",
+			)
+			continue
+		}
+
+		s.actionFuncs[actionTypeResp.TypeName] = actionFunc
+	}
+
+	return s.actionFuncs, s.actionFuncsDiags
+}
+
+// ActionSchema returns the Action Schema for the given type name and
+// caches the result for later Action operations.
+func (s *Server) ActionSchema(ctx context.Context, actionType string) (fwschema.Schema, diag.Diagnostics) {
+	s.actionSchemasMutex.RLock()
+	actionSchema, ok := s.actionSchemas[actionType]
+	s.actionSchemasMutex.RUnlock()
+
+	if ok {
+		return actionSchema, nil
+	}
+
+	var diags diag.Diagnostics
+
+	actionImpl, actionDiags := s.Action(ctx, actionType)
+
+	diags.Append(actionDiags...)
+
+	if diags.HasError() {
+		return nil, diags
+	}
+
+	schemaReq := action.SchemaRequest{}
+	schemaResp := action.SchemaResponse{}
+
+	logging.FrameworkTrace(ctx, "Calling provider defined Action Schema method", map[string]interface{}{logging.KeyActionType: actionType})
+	actionImpl.Schema(ctx, schemaReq, &schemaResp)
+	logging.FrameworkTrace(ctx, "Called provider defined Action Schema method", map[string]interface{}{logging.KeyActionType: actionType})
+
+	diags.Append(schemaResp.Diagnostics...)
+
+	if diags.HasError() {
+		return schemaResp.Schema, diags
+	}
+
+	s.actionSchemasMutex.Lock()
+
+	if s.actionSchemas == nil {
+		s.actionSchemas = make(map[string]fwschema.Schema)
+	}
+
+	s.actionSchemas[actionType] = schemaResp.Schema
+
+	s.actionSchemasMutex.Unlock()
+
+	return schemaResp.Schema, diags
+}