ephemeral: Initial ephemeral resource type implementation (#1050)

* initial ephemeral resource interfaces

* add ephemeral resource configure data

* attribute implementations

* uncomment custom type tests

* added block implementations

* add nested attribute implementations

* add schema test

* remove todo

* doc updates, renames, removals

* initial protov5 + fwserver implementation (protov6 stubbed)

* add fromproto5 tests

* add toproto5 tests

* add proto5server tests

* implement protov6

* schema + metadata tests

* add close proto5/6 tests

* add fwserver tests for schema/metadata

* prevent random false positives

* validate fwserver tests

* open/renew/close fwserver tests

* update error message

* update plugin go

* remove `config` from renew

* remove state from renew/close, add deferred action support

* update doc comments

* add experimental note

* add changelogs

* initial website documentation

* build(deps): Bump github.com/hashicorp/terraform-plugin-go (#1051)

Bumps [github.com/hashicorp/terraform-plugin-go](https://github.com/hashicorp/terraform-plugin-go) from 0.24.0 to 0.25.0.
- [Release notes](https://github.com/hashicorp/terraform-plugin-go/releases)
- [Changelog](https://github.com/hashicorp/terraform-plugin-go/blob/main/CHANGELOG.md)
- [Commits](hashicorp/terraform-plugin-go@v0.24.0...v0.25.0)

---
updated-dependencies:
- dependency-name: github.com/hashicorp/terraform-plugin-go
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Update website/docs/plugin/framework/ephemeral-resources/renew.mdx

Co-authored-by: Selena Goods <[email protected]>

* Update website/docs/plugin/framework/ephemeral-resources/validate-configuration.mdx

Co-authored-by: Selena Goods <[email protected]>

* adjust package docs

---------

Author: austinvalle

.changes/unreleased/ENHANCEMENTS-20241028-130457.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'provider: Added `ProviderWithEphemeralResources` interface for implementing
+  ephemeral resources'
+time: 2024-10-28T13:04:57.796703-04:00
+custom:
+  Issue: "1050"

.changes/unreleased/ENHANCEMENTS-20241028-130618.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'tfsdk: Added `EphemeralResultData` struct for representing ephemeral values
+  produced by a provider, such as from an ephemeral resource'
+time: 2024-10-28T13:06:18.799164-04:00
+custom:
+  Issue: "1050"

.changes/unreleased/ENHANCEMENTS-20241028-130758.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'provider: Added `EphemeralResourceData` to `ConfigureResponse`, to pass provider-defined
+  data to `ephemeral.EphemeralResource` implementations'
+time: 2024-10-28T13:07:58.9914-04:00
+custom:
+  Issue: "1050"

.changes/unreleased/FEATURES-20241028-130339.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'ephemeral: New package for implementing ephemeral resources'
+time: 2024-10-28T13:03:39.23218-04:00
+custom:
+  Issue: "1050"

.changes/unreleased/FEATURES-20241028-130855.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'ephemeral/schema: New package for implementing ephemeral resource schemas'
+time: 2024-10-28T13:08:55.520004-04:00
+custom:
+  Issue: "1050"

.changes/unreleased/NOTES-20241028-130308.yaml

@@ -0,0 +1,6 @@
+kind: NOTES
+body: Ephemeral resource support is in technical preview and offered without compatibility
+  promises until Terraform 1.10 is generally available.
+time: 2024-10-28T13:03:08.373897-04:00
+custom:
+  Issue: "1050"

ephemeral/close.go

@@ -0,0 +1,30 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+package ephemeral
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/internal/privatestate"
+)
+
+// 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 {
+	// Private is provider-defined ephemeral resource private state data
+	// which was previously provided by the latest Open or Renew operation.
+	//
+	// Use the GetKey method to read data.
+	Private *privatestate.ProviderData
+}
+
+// CloseResponse represents a response to a CloseRequest. An
+// instance of this response struct is supplied as an argument
+// to the ephemeral resource's Close function, in which the provider
+// should set values on the CloseResponse as appropriate.
+type CloseResponse struct {
+	// Diagnostics report errors or warnings related to closing the
+	// resource. An empty slice indicates a successful operation with no
+	// warnings or errors generated.
+	Diagnostics diag.Diagnostics
+}

ephemeral/config_validator.go

@@ -0,0 +1,28 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+package ephemeral
+
+import "context"
+
+// ConfigValidator describes reusable EphemeralResource configuration validation functionality.
+type ConfigValidator interface {
+	// Description describes the validation in plain text formatting.
+	//
+	// This information may be automatically added to ephemeral resource plain text
+	// descriptions by external tooling.
+	Description(context.Context) string
+
+	// MarkdownDescription describes the validation in Markdown formatting.
+	//
+	// This information may be automatically added to ephemeral resource Markdown
+	// descriptions by external tooling.
+	MarkdownDescription(context.Context) string
+
+	// ValidateEphemeralResource performs the validation.
+	//
+	// This method name is separate from the datasource.ConfigValidator
+	// interface ValidateDataSource method name, provider.ConfigValidator
+	// interface ValidateProvider method name, and resource.ConfigValidator
+	// interface ValidateResource method name to allow generic validators.
+	ValidateEphemeralResource(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
+}

ephemeral/configure.go

@@ -0,0 +1,33 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+package ephemeral
+
+import (
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+)
+
+// ConfigureRequest represents a request for the provider to configure an
+// ephemeral resource, i.e., set provider-level data or clients. An instance of
+// this request struct is supplied as an argument to the EphemeralResource type
+// Configure method.
+type ConfigureRequest struct {
+	// ProviderData is the data set in the
+	// [provider.ConfigureResponse.EphemeralResourceData] 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 EphemeralResource.
+	//
+	// 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
+// EphemeralResource type Configure method.
+type ConfigureResponse struct {
+	// Diagnostics report errors or warnings related to configuring of the
+	// EphemeralResource. An empty slice indicates a successful operation with no
+	// warnings or errors generated.
+	Diagnostics diag.Diagnostics
+}

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 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"
+}