Templating out Framework implementation for Pluggable State Storage

Author: rainkwan

go.mod

@@ -6,7 +6,7 @@ toolchain go1.24.4
 
 require (
 	github.com/google/go-cmp v0.7.0
-	github.com/hashicorp/terraform-plugin-go v0.29.0
+	github.com/hashicorp/terraform-plugin-go v0.29.1-0.20251028091959-b0e5c5f97a7c
 	github.com/hashicorp/terraform-plugin-log v0.9.0
 )
 
@@ -28,7 +28,7 @@ require (
 	golang.org/x/net v0.43.0 // indirect
 	golang.org/x/sys v0.35.0 // indirect
 	golang.org/x/text v0.28.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20250707201910-8d1bb00bc6a7 // indirect
-	google.golang.org/grpc v1.75.1 // indirect
-	google.golang.org/protobuf v1.36.9 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20250804133106-a7a43d27e69b // indirect
+	google.golang.org/grpc v1.76.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
 )

go.sum

@@ -23,8 +23,8 @@ github.com/hashicorp/go-plugin v1.7.0 h1:YghfQH/0QmPNc/AZMTFE3ac8fipZyZECHdDPshf
 github.com/hashicorp/go-plugin v1.7.0/go.mod h1:BExt6KEaIYx804z8k4gRzRLEvxKVb+kn0NMcihqOqb8=
 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.29.0 h1:1nXKl/nSpaYIUBU1IG/EsDOX0vv+9JxAltQyDMpq5mU=
-github.com/hashicorp/terraform-plugin-go v0.29.0/go.mod h1:vYZbIyvxyy0FWSmDHChCqKvI40cFTDGSb3D8D70i9GM=
+github.com/hashicorp/terraform-plugin-go v0.29.1-0.20251028091959-b0e5c5f97a7c h1:CZun5uZTGnQhElJBvo49mqvIBzQOPH2OSL6xazuzeQE=
+github.com/hashicorp/terraform-plugin-go v0.29.1-0.20251028091959-b0e5c5f97a7c/go.mod h1:KHRnT9vExG+r1fLxwOzOP6C6YXiaKHtsCIrky7teDYc=
 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.4.0 h1:S1yCGomj30Sao4l5BMPjTGZmCNzuv7/GDTDX99E9gTk=
@@ -86,12 +86,12 @@ golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
 golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
 gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
 gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20250707201910-8d1bb00bc6a7 h1:pFyd6EwwL2TqFf8emdthzeX+gZE1ElRq3iM8pui4KBY=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20250707201910-8d1bb00bc6a7/go.mod h1:qQ0YXyHHx3XkvlzUtpXDkS29lDSafHMZBAZDc03LQ3A=
-google.golang.org/grpc v1.75.1 h1:/ODCNEuf9VghjgO3rqLcfg8fiOP0nSluljWFlDxELLI=
-google.golang.org/grpc v1.75.1/go.mod h1:JtPAzKiq4v1xcAB2hydNlWI2RnF85XXcV0mhKXr2ecQ=
-google.golang.org/protobuf v1.36.9 h1:w2gp2mA27hUeUzj9Ex9FBjsBm40zfaDtEWow293U7Iw=
-google.golang.org/protobuf v1.36.9/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXntxiD/uRU=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20250804133106-a7a43d27e69b h1:zPKJod4w6F1+nRGDI9ubnXYhU9NSWoFAijkHkUXeTK8=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20250804133106-a7a43d27e69b/go.mod h1:qQ0YXyHHx3XkvlzUtpXDkS29lDSafHMZBAZDc03LQ3A=
+google.golang.org/grpc v1.76.0 h1:UnVkv1+uMLYXoIz6o7chp59WfQUYA2ex/BXQ9rHZu7A=
+google.golang.org/grpc v1.76.0/go.mod h1:Ju12QI8M6iQJtbcsV+awF5a4hfJMLi4X0JLo94ULZ6c=
+google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
+google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

provider/provider.go

@@ -164,3 +164,16 @@ type ProviderWithValidateConfig interface {
 	// ValidateConfig performs the validation.
 	ValidateConfig(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
 }
+
+// ProviderWithStateStores is an interface type that extends Provider to include state store.
+type ProviderWithStateStores interface {
+	Provider
+
+	// StateStores returns a slice of functions to instantiate each
+	// StateStore implementation.
+	//
+	// The state store type name is determined by the
+	// StateStore implementing the Metadata method. All state
+	// stores must have unique names.
+	StateStores(context.Context) []func() statestore.StateStore
+}

statestore/config_validator.go

@@ -0,0 +1,27 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package statestore
+
+import "context"
+
+// ConfigValidator describes reusable state store configuration validation functionality.
+type ConfigValidator interface {
+	// Description describes the validation in plain text formatting.
+	//
+	// This information may be automatically added to state store plain text
+	// descriptions by external tooling.
+	Description(context.Context) string
+
+	// MarkdownDescription describes the validation in Markdown formatting.
+	//
+	// This information may be automatically added to state store Markdown
+	// descriptions by external tooling.
+	MarkdownDescription(context.Context) string
+
+	// ValidateStateStore performs the validation.
+	//
+	// This method name is separate from ConfigValidators in resource and other packages in
+	// order to allow generic validators.
+	ValidateStateStore(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
+}

statestore/configure.go

@@ -0,0 +1,32 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package statestore
+
+import "github.com/hashicorp/terraform-plugin-framework/diag"
+
+// ConfigureRequest represents a request for the provider to configure an
+// state store, i.e., set provider-level data or clients. An instance of this
+// request struct is supplied as an argument to the StateStore type Configure
+// method.
+type ConfigureRequest struct {
+	// ProviderData is the data set in the
+	// [provider.ConfigureResponse.StateStoreData] field. This data is
+	// provider-specific and therefore can contain any necessary remote system
+	// clients, custom provider data, or anything else pertinent to the
+	// functionality of the StateStore.
+	//
+	// 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
+// StateStore 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
+}

statestore/delete_states.go

@@ -0,0 +1,39 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package statestore
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/internal/privatestate"
+)
+
+// DeleteStatesRequest represents a request for the provider to delete a
+// state. An instance of this request struct is supplied as an argument to
+// the state's DeleteStates function.
+type DeleteStatesRequest struct {
+	// Private is provider-defined state private state data which was previously
+	// stored with the state state.
+	//
+	// Use the GetKey method to read data.
+	Private *privatestate.ProviderData
+}
+
+// DeleteStatesResponse represents a response to a DeleteStatesRequest. An
+// instance of this response struct is supplied as
+// an argument to the state's DeleteStates function, in which the provider
+// should set values on the DeleteStatesResponse as appropriate.
+type DeleteStatesResponse struct {
+	// Private is the private state data following the DeleteStates
+	// operation. This field is pre-populated from DeleteStatesRequest.Private and
+	// can be modified during the state's DeleteStates operation in cases where
+	// an error diagnostic is being returned. Otherwise if no error diagnostic
+	// is being returned, indicating that the state was successfully deleted,
+	// this data will be automatically cleared to prevent Terraform errors.
+	Private *privatestate.ProviderData
+
+	// Diagnostics report errors or warnings related to deleting the
+	// state. An empty slice indicates a successful operation with no
+	// warnings or errors generated.
+	Diagnostics diag.Diagnostics
+}

statestore/get_states.go

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

statestore/lock.go

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

statestore/metadata.go

@@ -0,0 +1,24 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package statestore
+
+// MetadataRequest represents a request for the StateStore to return metadata,
+// such as its type name. An instance of this request struct is supplied as
+// an argument to the StateStore 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 StateStore 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
+// StateStore type Metadata method.
+type MetadataResponse struct {
+	// TypeName should be the full state store type, including the provider
+	// type prefix and an underscore. For example, examplecloud_thing.
+	TypeName string
+}

statestore/read.go

@@ -0,0 +1,50 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package statestore
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
+)
+
+// ReadClientCapabilities allows Terraform to publish information
+// regarding optionally supported protocol features for the ReadStateStore RPC,
+// such as forward-compatible Terraform behavior changes.
+type ReadClientCapabilities struct {
+}
+
+// ReadRequest represents a request for the provider to read a data
+// source, i.e., update values in state according to the real state of the
+// state store. An instance of this request struct is supplied as an argument
+// to the state store's Read function.
+type ReadRequest struct {
+	// Config is the configuration the user supplied for the state store.
+	//
+	// 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
+
+	// ProviderMeta is metadata from the provider_meta block of the module.
+	ProviderMeta tfsdk.Config
+
+	// ClientCapabilities defines optionally supported protocol features for the
+	// ReadStateStore RPC, such as forward-compatible Terraform behavior changes.
+	ClientCapabilities ReadClientCapabilities
+}
+
+// ReadResponse represents a response to a ReadRequest. An
+// instance of this response struct is supplied as an argument to the data
+// source's Read function, in which the provider should set values on the
+// ReadResponse as appropriate.
+type ReadResponse struct {
+	// State is the state of the state store following the Read operation.
+	// This field should be set during the resource's Read operation.
+	State tfsdk.State
+
+	// Diagnostics report errors or warnings related to reading the data
+	// source. An empty slice indicates a successful operation with no
+	// warnings or errors generated.
+	Diagnostics diag.Diagnostics
+}