implemented reuse option (#51)

* implemented reuse option

the new optional `reuse` attribute allows to re-assign freed keys
instead of enforcing incremental values.

fixes #50

* refactoring of README.md

* added usage example for `reuse`
* fixed required Go version (according to go.mod)
* updated Go link
* cleanup

Author: thewilli

README.md

@@ -1,37 +1,98 @@
 # Persistent Counter provider for Terraform
 
-```
+This provider allows to assign unique, increasing integers to string keys
+maintaining the same value per key while the key stays assigned.
+
+## Example
+
+```terraform
 terraform {
   required_providers {
     persistent = {
-      source = "rosmo/persistent"
+      source  = "rosmo/persistent"
+      version = ">=0.1.11"
     }
   }
 }
 
-resource "persistent_counter" "example" {
-  keys     = ["a", "b", "c"]
+variable input {
+  type = set(string)
 }
 
-# Result would be:
-#   persistent_counter.example.values = { a = 0, b = 1, c = 2 }
+resource "persistent_counter" "with-reuse" {
+  initial_value = 1
+  keys          = var.input
+  reuse         = true
+}
 
-# Changing the keys:
-resource "persistent_counter" "example" {
-  keys     = ["a", "b", "d", "c"]
+resource "persistent_counter" "without-reuse" {
+  initial_value = 1
+  keys          = var.input
+  reuse         = false
 }
 
-# New result would be:
-#   persistent_counter.example.values = { a = 0, b = 1, d = 3, c = 2 }
+output counters {
+  value = {
+    "with-reuse" = persistent_counter.with-reuse.values,
+    "without-reuse" = persistent_counter.without-reuse.values,
+  }
+}
+```
+
+Run the example providing an initial value as input results in the following output:
 
+```shell
+$ terraform apply -auto-approve -var 'input=["c","b","a"]'
+
+counters = {
+  "with-reuse" = tomap({
+    "a" = 1
+    "b" = 2
+    "c" = 3
+  })
+  "without-reuse" = tomap({
+    "a" = 1
+    "b" = 2
+    "c" = 3
+  })
+}
 ```
 
-The provider is available from Terraform registry: [registry.terraform.io/providers/rosmo/persistent/latest](https://registry.terraform.io/providers/rosmo/persistent/latest)
+If values were just added, both, the version with and without `reuse` enabled
+behave the same. Also note, that keys are always sorted ascending, before counter
+values are assigned to them.
+
+The difference the two versions in this example can be made clear when exchanging
+an element (i.e. removing a value and adding a new one at the same time):
+
+```shell
+$ terraform apply -auto-approve -var 'input=["c","a","d"]'
+
+counters = {
+  "with-reuse" = tomap({
+    "a" = 1
+    "c" = 3
+    "d" = 2
+  })
+  "without-reuse" = tomap({
+    "a" = 1
+    "c" = 3
+    "d" = 4
+  })
+}
+```
+
+When `reuse` is set to `true`, the counter will re-assign values that are no
+longer in use, while a value of `false` will always emit unique, ascending values.
+
+## Usage
+
+The provider is available from Terraform registry: [registry.terraform.io/providers/rosmo/persistent/latest](https://registry.terraform.io/providers/rosmo/persistent/latest).
 
 ## Requirements
 
 - [Terraform](https://www.terraform.io/downloads.html) >= 1.0
-- [Go](https://golang.org/doc/install) >= 1.18
+- [Go](https://go.dev/doc/install) >= 1.21 (building from source only)
 
 ## Building The Provider
 
@@ -42,4 +103,3 @@ The provider is available from Terraform registry: [registry.terraform.io/provid
 ```shell
 go install
 ```
-

internal/provider/assignment.go

@@ -0,0 +1,50 @@
+package provider
+
+import (
+	"slices"
+)
+
+// assignKeys assigns counter values to the keys provided as input
+func assignKeys(keys []string, state map[string]int64, reuse bool, initial int64, last int64) (int64, map[string]int64) {
+	// Create a map to hold the assigned values
+	assignedValues := make(map[string]int64, len(keys))
+	// Create a list of values for easier tracking for the next possible one
+	values := make([]int64, 0, len(keys))
+
+	// If the previous state is defined, maintain all entries that are still present in keys.
+	// Also handle a changing initial value.
+	for key, value := range state {
+		if slices.Contains(keys, key) && value >= initial {
+			assignedValues[key] = value
+			values = append(values, value)
+		}
+	}
+
+	// Sort keys to provide a predictable behaviour
+	slices.Sort(keys)
+
+	// Iterate over the keys and provide values to those not covered yet
+	for _, key := range keys {
+		// If the key has not yet a value assigned
+		if _, exists := assignedValues[key]; !exists {
+			// If reuse is true, find a value that does not exist in the assignedValues map
+			if reuse {
+				for i := initial; ; i++ {
+					if !slices.Contains(values, i) {
+						assignedValues[key] = i
+						values = append(values, i)
+						last = i
+						break
+					}
+				}
+			} else {
+				// If reuse is false, increment the last value and assign it to the key
+				last = max(last+1, initial)
+				assignedValues[key] = last
+			}
+		}
+	}
+
+	// Return the last value and the assignedValues map
+	return last, assignedValues
+}

internal/provider/assignment_test.go

@@ -0,0 +1,82 @@
+package provider
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestEmpty(t *testing.T) {
+	input := []string{}
+	initial := 5
+	last, res := assignKeys(input, nil, false, int64(initial), int64(initial))
+	t.Logf("input keys: %v, output: %v", input, res)
+	expectedLast := initial + len(input)
+	if last != int64(expectedLast) {
+		t.Errorf("Expecting last to be %d, got %d", expectedLast, last)
+	}
+	if len(res) != len(input) {
+		t.Errorf("Result map length %d != key length %d", len(res), len(input))
+	}
+}
+
+func TestInitial(t *testing.T) {
+	input := []string{"a", "c", "b"}
+	initial := 5
+	last, res := assignKeys(input, nil, false, int64(initial), int64(initial-1))
+	t.Logf("input keys: %v, output: %v", input, res)
+	expectedLast := initial + len(input) - 1
+	if last != int64(expectedLast) {
+		t.Errorf("Expecting last to be %d, got %d", expectedLast, last)
+	}
+	if len(res) != len(input) {
+		t.Errorf("Result map length %d != key length %d", len(res), len(input))
+	}
+	expected := map[string]int64{"a": 5, "b": 6, "c": 7}
+	if !reflect.DeepEqual(res, expected) {
+		t.Errorf("Expected %v got %v", expected, res)
+	}
+}
+
+func TestNop(t *testing.T) {
+	input := []string{"a", "c", "b"}
+	state := map[string]int64{"a": 5, "b": 9, "c": 11}
+	initial := 5
+	last := 11
+	last2, res := assignKeys(input, state, false, int64(initial), int64(last))
+	if !reflect.DeepEqual(res, state) {
+		t.Errorf("Expected %v got %v", state, res)
+	}
+	if int64(last) != last2 {
+		t.Errorf("Expected last value to stay at %d but got %d", last, last2)
+	}
+	last2, res = assignKeys(input, state, true, int64(initial), int64(last))
+	if !reflect.DeepEqual(res, state) {
+		t.Errorf("Expected %v got %v", state, res)
+	}
+	if int64(last) != last2 {
+		t.Errorf("Expected last value to stay at %d but got %d", last, last2)
+	}
+}
+
+func TestChange(t *testing.T) {
+	input := []string{"d", "a", "c"}
+	state := map[string]int64{"a": 5, "b": 6, "c": 7}
+	initial := 5
+	last := state["c"]
+	last2, res := assignKeys(input, state, false, int64(initial), int64(last))
+	expected := map[string]int64{"a": 5, "c": 7, "d": 8}
+	if !reflect.DeepEqual(res, expected) {
+		t.Errorf("Expected %v got %v", state, res)
+	}
+	if int64(last2) != last+1 {
+		t.Errorf("Expected last value to stay at %d but got %d", last, last2)
+	}
+	expected = map[string]int64{"a": 5, "c": 7, "d": 6}
+	last2, res = assignKeys(input, state, true, int64(initial), int64(last))
+	if !reflect.DeepEqual(res, expected) {
+		t.Errorf("Expected %v got %v", state, res)
+	}
+	if int64(last2) != expected["d"] {
+		t.Errorf("Expected last value to stay at %d but got %d", state["b"], last2)
+	}
+}

internal/provider/counter_resource.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"net/http"
 
+	"github.com/hashicorp/terraform-plugin-framework/attr"
 	"github.com/hashicorp/terraform-plugin-framework/path"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
@@ -28,6 +29,7 @@ type PersistentCounterResource struct {
 type PersistentCounterResourceModel struct {
 	Id           types.String `tfsdk:"id"`
 	Keys         types.List   `tfsdk:"keys"`
+	Reuse        types.Bool   `tfsdk:"reuse"`
 	InitialValue types.Int64  `tfsdk:"initial_value"`
 	LastValue    types.Int64  `tfsdk:"last_value"`
 	Values       types.Map    `tfsdk:"values"`
@@ -59,6 +61,10 @@ func (r *PersistentCounterResource) Schema(ctx context.Context, req resource.Sch
 				ElementType: types.StringType,
 				Required:    true,
 			},
+			"reuse": schema.BoolAttribute{
+				Description: "Allows reusing freed keys for new ones.",
+				Optional:    true,
+			},
 			"initial_value": schema.Int64Attribute{
 				Optional:    true,
 				Computed:    true,
@@ -115,21 +121,16 @@ func (r *PersistentCounterResource) Create(ctx context.Context, req resource.Cre
 
 	// Generate new set of keys
 	if data.Values.IsUnknown() {
-		keys := data.Keys.Elements()
-		keysLength := len(keys)
-		values := make(map[string]int64, keysLength)
-		currentValue := data.InitialValue.ValueInt64()
-		for i := 0; i < keysLength; i++ {
-			_keyValue, ok := keys[i].(types.String)
-			if !ok {
-				continue
-			}
-			keyValue := _keyValue.ValueString()
-			values[keyValue] = currentValue
-			currentValue += 1
-		}
-		data.LastValue = types.Int64Value(currentValue - 1)
+		keys := convertKeys(data.Keys.Elements())
+		last, values := assignKeys(
+			keys, nil, data.Reuse.ValueBool(),
+			// initial value
+			data.InitialValue.ValueInt64(),
+			// use initial value - 1 for last value
+			data.InitialValue.ValueInt64()-1,
+		)
 
+		data.LastValue = types.Int64Value(last)
 		_values, diags := types.MapValueFrom(ctx, types.Int64Type, values)
 		resp.Diagnostics.Append(diags...)
 		if resp.Diagnostics.HasError() {
@@ -165,33 +166,20 @@ func (r *PersistentCounterResource) Update(ctx context.Context, req resource.Upd
 		return
 	}
 
-	if !data.Keys.Equal(state.Keys) {
-		lastValue := state.LastValue.ValueInt64()
-
-		keys := data.Keys.Elements()
-		keysLength := len(keys)
-		values := make(map[string]int64, keysLength)
-
-		stateValues := state.Values.Elements()
-		for _, key := range keys {
-			_keyValue, ok := key.(types.String)
-			if !ok {
-				continue
-			}
-			keyValue := _keyValue.ValueString()
-			if val, found := stateValues[keyValue]; found {
-				_intValue, ok := val.(types.Int64)
-				if !ok {
-					continue
-				}
-				values[keyValue] = _intValue.ValueInt64()
-			} else {
-				lastValue += 1
-				values[keyValue] = lastValue
-			}
-		}
-		data.LastValue = types.Int64Value(lastValue)
+	if !data.Keys.Equal(state.Keys) || !data.InitialValue.Equal(state.Keys) {
+
+		keys := convertKeys(data.Keys.Elements())
+		stateVals := convertState(state.Values.Elements())
+
+		last, values := assignKeys(
+			keys, stateVals, data.Reuse.ValueBool(),
+			data.InitialValue.ValueInt64(),
+			state.LastValue.ValueInt64(),
+		)
+
+		data.LastValue = types.Int64Value(last)
 		state.LastValue = data.LastValue
+
 		_values, diags := types.MapValueFrom(ctx, types.Int64Type, values)
 		resp.Diagnostics.Append(diags...)
 		if resp.Diagnostics.HasError() {
@@ -226,3 +214,36 @@ func (r *PersistentCounterResource) Delete(ctx context.Context, req resource.Del
 func (r *PersistentCounterResource) ImportState(ctx context.Context, req resource.ImportStateRequest, resp *resource.ImportStateResponse) {
 	resource.ImportStatePassthroughID(ctx, path.Root("id"), req, resp)
 }
+
+// convertKeys generates a string slice from the terraform string list representation
+func convertKeys(tfKeys []attr.Value) []string {
+	keys := make([]string, 0, len(tfKeys))
+	for _, k := range tfKeys {
+		val, ok := k.(types.String)
+		if !ok {
+			// conversion failed
+			continue
+		}
+		str := val.ValueString()
+		if str == "" {
+			// invalid string value or string empty
+			continue
+		}
+		keys = append(keys, str)
+
+	}
+	return keys
+}
+
+// convertState converts the counter state from terraform format to map[string]int64
+func convertState(tfState map[string]attr.Value) map[string]int64 {
+	state := make(map[string]int64, len(tfState))
+	for k, v := range tfState {
+		intVal, ok := v.(types.Int64)
+		if !ok {
+			continue
+		}
+		state[k] = intVal.ValueInt64()
+	}
+	return state
+}