statestore

type ConfigValidator interface {
	// Description describes the validation in plain text formatting.
	//
	// This information may be automatically added to statestore plain text
	// descriptions by external tooling.
	Description(context.Context) string

	// MarkdownDescription describes the validation in Markdown formatting.
	//
	// This information may be automatically added to statestore Markdown
	// descriptions by external tooling.
	MarkdownDescription(context.Context) string

	// ValidateStateStore performs the validation.
	//
	// This method name is separate from ConfigValidators in datasource and other packages in
	// order to allow generic validators.
	ValidateStateStore(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
}

type ConfigureRequest struct {
	// StateStoreData is the data set in the [InitializeResponse.StateStoreData] field.
	// This data can contain any necessary remote system clients, state store initialization data,
	// or anything else pertinent to the functionality of the StateStore.
	//
	// This data is only set after the ConfigureStateStore RPC has been called by Terraform.
	StateStoreData any
}

type ConfigureResponse struct {
	// Diagnostics report errors or warnings related to configuring of the
	// StateStore. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

type DeleteStateRequest struct {
	// StateID is the ID of the state to delete.
	//
	// Typically this is the name of the Terraform workspace the practitioner is
	// running Terraform in: https://developer.hashicorp.com/terraform/language/state/workspaces .
	//
	// If the practitioner hasn't explicitly selected a workspace, StateID will be set to "default".
	StateID string
}

type DeleteStateResponse struct {
	// Diagnostics report errors or warnings related to deleting a state in the configured
	// state store. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

type GetStatesRequest struct{}

type GetStatesResponse struct {
	// StateIDs is a list of all state IDs for states persisted in the configured state store.
	StateIDs []string

	// Diagnostics report errors or warnings related to retrieving all state IDs for states
	// persisted in the configured state store. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

type InitializeRequest struct {
	// Config is the configuration the user supplied for the state store.
	Config tfsdk.Config

	// ProviderData is the data set in the [provider.ConfigureResponse.StateStoreData]
	// 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 StateStore.
	ProviderData any
}

type InitializeResponse struct {
	// Diagnostics report errors or warnings related to initializing the
	// state store. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics

	// StateStoreData is a combination of provider-defined and state store specific data that is
	// passed to [ConfigureRequest.StateStoreData] for the implementing StateStore type.
	StateStoreData any
}

type LockInfo struct {
	// ID is a unique identifier for a lock. The [NewLockInfo] function should be
	// used to create a new LockInfo struct, where this ID will be generated.
	//
	// This field should be used to set [LockResponse.LockID].
	ID string `json:"id"`

	// Operation is the operation provided by the [LockRequest] (plan, apply, refresh, etc.)
	Operation string `json:"operation"`

	// Who is a string representing the <username>@<hostname> (if available).
	Who string `json:"who,omitempty"`

	// Created is the time that the lock was created, set by [NewLockInfo].
	Created time.Time `json:"created"`
}

type LockRequest struct {
	// StateID is the ID of the state to lock.
	//
	// Typically this is the name of the Terraform workspace the practitioner is
	// running Terraform in: https://developer.hashicorp.com/terraform/language/state/workspaces .
	//
	// If the practitioner hasn't explicitly selected a workspace, StateID will be set to "default".
	StateID string

	// Operation represents the type of operation Terraform is running when requesting the lock (refresh, plan, apply, etc).
	Operation string
}

type LockResponse struct {
	// LockID is an opaque string representing a new lock that has been persisted in the configured state store
	// for a given state ([LockRequest.StateID]). LockID is determined by the provider and will be passed to
	// [UnlockRequest.LockID] to release the lock once the operation is complete.
	//
	// If the state store doesn't support locking or the current state store configuration is not setup for locking,
	// return the LockResponse with LockID unset and no diagnostics. This will inform Terraform the state store cannot be locked,
	// which will skip unlocking the state when the operation is complete.
	//
	// If the given state ([LockRequest.StateID]) has already been locked, the provider should return an error diagnostic with
	// information about the current lock. If the [LockInfo] struct is being used, this diagnostic can be created with the
	// [WorkspaceAlreadyLockedDiagnostic] function.
	LockID string

	// Diagnostics report errors or warnings related to locking a state in the given
	// state store. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

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
}

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
}

type ReadRequest struct {
	// StateID is the ID of the state to read.
	//
	// Typically, this is the name of the Terraform workspace the practitioner is
	// running Terraform in: https://developer.hashicorp.com/terraform/language/state/workspaces .
	//
	// If the practitioner hasn't explicitly selected a workspace, StateID will be set to "default".
	StateID string
}

type ReadResponse struct {
	// Diagnostics report errors or warnings related to reading the given state
	// from the state store. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics

	// StateBytes is the entire state file for [ReadRequest.StateID].
	StateBytes []byte
}

type SchemaRequest struct{}

type SchemaResponse struct {
	// Schema is the schema of the state store.
	Schema schema.Schema

	// Diagnostics report errors or warnings related to retrieving the state store schema.
	// An empty slice indicates success, with no warnings or errors generated.
	Diagnostics diag.Diagnostics
}

type StateStore interface {
	// Metadata should return the full name of the state store, such
	// as examplecloud_store.
	Metadata(context.Context, MetadataRequest, *MetadataResponse)

	// Schema should return the schema for this state store.
	Schema(context.Context, SchemaRequest, *SchemaResponse)

	// Initialize is called one time, prior to executing any state store RPCs (excluding offline validation) but after
	// the provider is configured, and is when Terraform sends the values the user specified in the state_store configuration
	// block to the provider. These are supplied in the InitializeRequest argument.
	//
	// As this method is always executed after provider configuration, data can be passed from [provider.ConfigureResponse.StateStoreData]
	// to [InitializeRequest.ProviderData]. This provider-level data along with the values from state store configuration are often used
	// to initialize an API client, which can be set to [InitializeResponse.StateStoreData], then eventually stored on the struct implementing
	// the StateStore interface in the [StateStoreWithConfigure.Configure] method.
	Initialize(context.Context, InitializeRequest, *InitializeResponse)

	// GetStates returns all state IDs for states persisted in the configured state store.
	GetStates(context.Context, GetStatesRequest, *GetStatesResponse)

	// DeleteState is called by Terraform to delete a state from the configured state store.
	DeleteState(context.Context, DeleteStateRequest, *DeleteStateResponse)

	// Lock is called by Terraform to acquire a lock prior to performing an operation that needs to write to state. If the [LockResponse.LockID] field
	// is a non-empty string, Terraform will call [StateStore.Unlock] once the operation has been completed.
	//
	// State stores that support locking are expected to handle concurrent clients by ensuring multiple locks cannot be acquired on the same state
	// simultaneously. The backing data store must be strongly consistent (i.e. a newly created lock is immediately visible to all clients) and some form
	// of concurrency control must be implemented when attempting to acquire a lock. An example of this would be creating a lock file with a conditional
	// write that would fail if the requested file already exists.
	Lock(context.Context, LockRequest, *LockResponse)

	// Unlock is called by Terraform to release a lock (previously acquired by [StateStore.Lock]) after an operation has been completed.
	//
	// This method is not called by Terraform if the state store returns an empty [LockResponse.LockID] from [StateStore.Lock].
	Unlock(context.Context, UnlockRequest, *UnlockResponse)

	// Read returns the given state as bytes from a state store.
	Read(context.Context, ReadRequest, *ReadResponse)

	// Write is called by Terraform to write state data to a given state ID in a state store.
	Write(context.Context, WriteRequest, *WriteResponse)
}

type StateStoreWithConfigValidators interface {
	StateStore

	// ConfigValidators returns a list of functions which will all be performed during validation.
	ConfigValidators(context.Context) []ConfigValidator
}

type StateStoreWithConfigure interface {
	StateStore

	// Configure enables provider-level data or clients to be set in the
	// provider-defined StateStore type.
	Configure(context.Context, ConfigureRequest, *ConfigureResponse)
}

type StateStoreWithValidateConfig interface {
	StateStore

	// ValidateConfig performs the validation.
	ValidateConfig(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
}

type UnlockRequest struct {
	// StateID is the ID of the state to unlock.
	//
	// Typically this is the name of the Terraform workspace the practitioner is
	// running Terraform in: https://developer.hashicorp.com/terraform/language/state/workspaces .
	//
	// If the practitioner hasn't explicitly selected a workspace, StateID will be set to "default".
	StateID string

	// LockID is the ID of the lock to be released (unlocked) for a given state in the configured state store.
	// This is the same value that is returned when originally acquiring the lock from the [StateStore.Lock] method,
	// i.e. the [LockResponse.LockID] field.
	//
	// The provider should return a diagnostic if a lock doesn't exist in the state store for the given state, or if the lock ID
	// for the given state doesn't match LockID. These scenarios likely indicate either a bug in the [StateStore.Lock] method
	// or the underlying storage mechanism where multiple concurrent clients were able to acquire a lock on the same state.
	LockID string
}

type UnlockResponse struct {
	// Diagnostics report errors or warnings related to unlocking a state in the given
	// state store. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

type ValidateConfigRequest 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
}

type ValidateConfigResponse struct {
	// Diagnostics report errors or warnings related to validating the state store
	// configuration. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

type WriteRequest struct {
	// StateID is the ID of the state to write to.
	//
	// Typically this is the name of the Terraform workspace the practitioner is
	// running Terraform in: https://developer.hashicorp.com/terraform/language/state/workspaces .
	//
	// If the practitioner hasn't explicitly selected a workspace, StateID will be set to "default".
	StateID string

	// StateBytes is the entire state file to write to [WriteRequest.StateID].
	StateBytes []byte
}

type WriteResponse struct {
	// Diagnostics report errors or warnings related to writing state data to a
	// state store. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}