feat!: implemented value_path_exists

Author: teneko

docs/resources/path_exists.md

@@ -0,0 +1,67 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "value_path_exists Resource - terraform-provider-value"
+subcategory: ""
+description: |-
+  Checks if an OS path exists and caches its computation at plan-time and won't change afterapply-time even the path may have been removed.
+  Provider Metadata
+  Each module can use providermeta. Please keep in mind that these settings only count for resources of this module! (see https://www.terraform.io/internals/provider-meta https://www.terraform.io/internals/provider-meta):
+  ```terraform
+  // Terraform providermeta example
+  terraform {
+      // "value" is the provider name
+      providermeta "value" {
+          // {workdir} -> The only available placeholder currently (see below for more information)
+          guidseed_addition = "{workdir}#for-example" // Results into "/path/to/workdir#for-example"
+      }
+  }
+  ```
+  Optional
+  guid_seed_addition (String) It serves as addition to each seed of any value_is_fully_known (resource) or value_is_known (resource) within the project if specified in provider, or within the same module if specified in provider-meta.
+  Placeholders:
+  "{workdir}" (Keyword) The actual workdir; equals to terraform's path.root. This placeholder is
+  recommended because this value won't be dragged along the plan and apply phase in comparison to
+  "abspath(path.root)" that you would add to resource seed where a change to path.root would be
+  recognized just as usual from terraform.
+---
+
+# value_path_exists (Resource)
+
+Checks if an OS path exists and caches its computation at plan-time and won't change afterapply-time even the path may have been removed.
+## Provider Metadata
+Each module can use provider_meta. Please keep in mind that these settings only count for resources of this module! (see [https://www.terraform.io/internals/provider-meta](https://www.terraform.io/internals/provider-meta)):
+```terraform
+// Terraform provider_meta example
+terraform {
+	// "value" is the provider name
+	provider_meta "value" {
+		// {workdir} -> The only available placeholder currently (see below for more information)
+		guid_seed_addition = "{workdir}#for-example" // Results into "/path/to/workdir#for-example"
+	}
+}
+```
+### Optional
+- `guid_seed_addition` (String) It serves as addition to each seed of any `value_is_fully_known` (resource) or `value_is_known` (resource) within the project if specified in provider, or within the same module if specified in provider-meta.
+
+	**Placeholders**:
+	- "{workdir}" (Keyword) The actual workdir; equals to terraform's path.root. This placeholder is
+	recommended because this value won't be dragged along the plan and apply phase in comparison to
+	"abspath(path.root)" that you would add to resource seed where a change to path.root would be
+	recognized just as usual from terraform.
+
+
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `guid_seed` (String) Attention! The seed is being used to determine resource uniqueness prior (first plan phase) and during apply phase (second plan phase). Very important to state is that the **seed must be fully known during the plan phase**, otherwise, an error is thrown. Within one terraform plan & apply the **seed of every "value_path_exists" must be unique**! I really recommend you to use the provider configuration and/or provider_meta configuration to increase resource uniqueness. Besides `guid_seed`, the provider configuration seed, the provider_meta configuration seed and the resource type itself will become part of the final seed. Under certain circumstances you may face problems if you run terraform concurrenctly. If you do so, then I recommend you to pass-through a random value via a user (environment) variable that you then add to the seed.
+- `path` (String) A path to a file or directory.
+- `proposed_unknown` (Boolean) It is very crucial that this field is **not** filled by any custom value except the one produced by `value_unknown_proposer` (resource). This has the reason as its `value` is **always** unknown during the plan phase. On this behaviour this resource must rely and it cannot check if you do not so!
+
+### Read-Only
+
+- `exists` (Boolean) The computation whether the path exists or not.
+
+

examples/replaced_when/file_inexistence_check/findme

@@ -7,17 +7,36 @@ terraform {
   }
 }
 
-resource "value_replaced_when" "findme_inexistence" {
-  for_each = {
+resource "value_unknown_proposer" "default" {}
+
+locals {
+  files = {
     "findme" : {
       fullname = "${path.module}/findme"
     }
   }
+}
+
+resource "value_path_exists" "findme" {
+  path             = local.files["findme"].fullname
+  guid_seed        = "findme"
+  proposed_unknown = value_unknown_proposer.default.value
+}
+
+resource "value_replaced_when" "findme_inexistence" {
+  condition = !value_path_exists.findme.exists
+}
+
+resource "local_file" "findme" {
+  count    = !value_path_exists.findme.exists ? 1 : 0
+  content  = ""
+  filename = local.files["findme"].fullname
+}
 
-  condition = !fileexists(each.value.fullname)
+output "is_findme_inexistent" {
+  value = !value_path_exists.findme.exists
 }
 
-output "findme_inexistence_check" {
-  // On craetion this should contain a non-null value.value
-  value = value_replaced_when.findme_inexistence
+output "findme_inexistence_caused_new_value" {
+  value = value_replaced_when.findme_inexistence.value
 }

examples/replaced_when/file_inexistence_check/main.tf

@@ -0,0 +1,218 @@
+package fwkprovider
+
+import (
+	"context"
+	"os"
+	"strconv"
+
+	"github.com/pseudo-dynamic/terraform-provider-value/internal/fwkproviderconfig"
+	"github.com/pseudo-dynamic/terraform-provider-value/internal/goproviderconfig"
+	"github.com/pseudo-dynamic/terraform-provider-value/internal/guid"
+
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/resource"
+	"github.com/hashicorp/terraform-plugin-framework/tfsdk"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+const pathExistsResourceSuffix string = "_path_exists"
+const pathExistsResourceName string = providerName + pathExistsResourceSuffix
+
+type pathExistsResource struct {
+	ProviderGuidSeedAddition *string
+}
+
+type pathExistsResourceWithTraits interface {
+	resource.ResourceWithMetadata
+	resource.ResourceWithGetSchema
+	resource.ResourceWithModifyPlan
+	resource.ResourceWithConfigure
+}
+
+func NewPathExistsResource() pathExistsResourceWithTraits {
+	return &pathExistsResource{}
+}
+
+// Configure implements pathExistsResourceWithTraits
+func (r *pathExistsResource) Configure(ctx context.Context, req resource.ConfigureRequest, resp *resource.ConfigureResponse) {
+	if req.ProviderData == nil {
+		// For whatever reason Configure gets called with nil ProviderData.
+		return
+	}
+
+	provderData := req.ProviderData.(*providerData)
+	r.ProviderGuidSeedAddition = provderData.GuidSeedAddition
+}
+
+func (r pathExistsResource) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
+	return tfsdk.Schema{
+		Description: "Checks if an OS path exists and caches its computation at plan-time and won't change after" +
+			"apply-time even the path may have been removed." + "\n" + goproviderconfig.GetProviderMetaGuidSeedAdditionAttributeDescription(),
+		Attributes: map[string]tfsdk.Attribute{
+			"path": {
+				Type:        types.StringType,
+				Required:    true,
+				Description: "A path to a file or directory.",
+			},
+			"proposed_unknown": {
+				Type:        types.BoolType,
+				Required:    true,
+				Description: goproviderconfig.GetProposedUnknownAttributeDescription(),
+			},
+			"guid_seed": {
+				Type:        types.StringType,
+				Required:    true,
+				Description: goproviderconfig.GetGuidSeedAttributeDescription(pathExistsResourceName),
+				Validators: []tfsdk.AttributeValidator{
+					&fwkproviderconfig.PlanKnownValidator{},
+				},
+			},
+			"exists": {
+				Type:        types.BoolType,
+				Computed:    true,
+				Description: "The computation whether the path exists or not.",
+			},
+		},
+	}, nil
+}
+
+type pathExistsState struct {
+	Path            types.String `tfsdk:"path"`
+	GuidSeed        types.String `tfsdk:"guid_seed"`
+	ProposedUnknown types.Bool   `tfsdk:"proposed_unknown"`
+	Exists          types.Bool   `tfsdk:"exists"`
+}
+
+func (r *pathExistsResource) Metadata(ctx context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
+	resp.TypeName = req.ProviderTypeName + pathExistsResourceSuffix
+}
+
+// ModifyPlan implements PathExistsResourceWithTraits
+func (r *pathExistsResource) ModifyPlan(ctx context.Context, req resource.ModifyPlanRequest, resp *resource.ModifyPlanResponse) {
+	if r.ProviderGuidSeedAddition == nil {
+		resp.Diagnostics.AddError("Bad provider guid seed", "Provider guid seed is null but was expected to be empty")
+		return
+	}
+
+	// Get current config
+	var config pathExistsState
+	diags := req.Config.Get(ctx, &config)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	suppliedGuidSeed := config.GuidSeed.Value
+	isPlanPhase := config.ProposedUnknown.IsUnknown()
+
+	var providerMetaSeedAddition string
+	var isSuccessful bool
+	if providerMetaSeedAddition, _, isSuccessful = goproviderconfig.TryUnmarshalValueThenExtractGuidSeedAddition(&req.ProviderMeta.Raw); !isSuccessful {
+		resp.Diagnostics.AddError("Extraction failed", "Could not extract provider meta guid seed addition")
+		return
+	}
+
+	composedGuidSeed := guid.ComposeGuidSeed(r.ProviderGuidSeedAddition,
+		&providerMetaSeedAddition,
+		pathExistsResourceName,
+		"exists",
+		&suppliedGuidSeed)
+
+	checkPathExistence := func() types.Bool {
+		if config.Path.Unknown {
+			return types.Bool{Unknown: true}
+		}
+
+		_, err := os.Stat(config.Path.Value)
+		pathExists := err == nil
+		return types.Bool{Value: pathExists}
+	}
+
+	cachedExists, err := guid.GetPlanCachedBoolean(
+		isPlanPhase,
+		composedGuidSeed,
+		pathExistsResourceName,
+		checkPathExistence)
+
+	if err != nil {
+		resp.Diagnostics.AddError("Plan cache mechanism failed for exists attribute", err.Error())
+		return
+	}
+
+	resp.Diagnostics.AddWarning("Exists (cached) is unknown: "+strconv.FormatBool(cachedExists.Unknown), "")
+
+	config.Exists = cachedExists
+	resp.Plan.Set(ctx, &config)
+}
+
+// Create a new resource
+func (r pathExistsResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	// Retrieve values from plan
+	var plan pathExistsState
+	diags := req.Plan.Get(ctx, &plan)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	diags = resp.State.Set(ctx, &plan)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+}
+
+// Read resource information
+func (r pathExistsResource) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
+	// Get current state
+	var state pathExistsState
+	diags := req.State.Get(ctx, &state)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	diags = resp.State.Set(ctx, &state)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+}
+
+// Update resource
+func (r pathExistsResource) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) {
+	// Get plan
+	var plan pathExistsState
+	diags := req.Plan.Get(ctx, &plan)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	// Set new state
+	diags = resp.State.Set(ctx, &plan)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+}
+
+// Delete resource
+func (r pathExistsResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	var state pathExistsState
+	diags := req.State.Get(ctx, &state)
+	resp.Diagnostics.Append(diags...)
+
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	// Remove resource from state
+	resp.State.RemoveResource(ctx)
+}

internal/fwkprovider/path_exists.go

@@ -12,6 +12,8 @@ import (
 	"github.com/pseudo-dynamic/terraform-provider-value/internal/fwkproviderconfig"
 )
 
+const providerName string = "value"
+
 type provider struct {
 }
 
@@ -26,6 +28,10 @@ type providerConfig struct {
 	GuidSeedAddition types.String `tfsdk:"guid_seed_addition"`
 }
 
+type providerData struct {
+	GuidSeedAddition *string
+}
+
 func NewProvider() providerWithTraits {
 	return &provider{}
 }
@@ -49,6 +55,10 @@ func (p *provider) Configure(ctx context.Context, req fwkprovider.ConfigureReque
 	if resp.Diagnostics.HasError() {
 		return
 	}
+
+	resp.ResourceData = &providerData{
+		GuidSeedAddition: &config.GuidSeedAddition.Value,
+	}
 }
 
 // GetResources - Defines provider resources
@@ -60,6 +70,9 @@ func (p *provider) Resources(_ context.Context) []func() resource.Resource {
 		func() resource.Resource {
 			return NewUnknownProposerResource()
 		},
+		func() resource.Resource {
+			return NewPathExistsResource()
+		},
 	}
 }
 

internal/fwkprovider/provider.go

@@ -7,28 +7,6 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/types"
 )
 
-type guidSeedAdditionUnknownValidator struct{}
-
-func (v *guidSeedAdditionUnknownValidator) Validate(ctx context.Context, req tfsdk.ValidateAttributeRequest, resp *tfsdk.ValidateAttributeResponse) {
-	if req.AttributeConfig != nil && req.AttributeConfig.IsUnknown() {
-		resp.Diagnostics.AddError(
-			"Guid seed addition is unknown",
-			"Guid seed addition must be fully known at plan-time. For further informations take a look into the documentation.")
-	}
-}
-
-func getGuidSeedAdditionUnknownValidatorDescription() string {
-	return "Validates that guid seed addition is not unknown."
-}
-
-func (*guidSeedAdditionUnknownValidator) Description(context.Context) string {
-	return getGuidSeedAdditionUnknownValidatorDescription()
-}
-
-func (*guidSeedAdditionUnknownValidator) MarkdownDescription(context.Context) string {
-	return getGuidSeedAdditionUnknownValidatorDescription()
-}
-
 type guidSeedAdditionDefaultEmptyModifier struct{}
 
 func (r guidSeedAdditionDefaultEmptyModifier) Modify(ctx context.Context, req tfsdk.ModifyAttributePlanRequest, resp *tfsdk.ModifyAttributePlanResponse) {