Add optional methods attribute to the arrstack role resource (#3)

## Why

Engine plugin v0.2.0 added a `methods` field to arrstack roles, pinning a minted arrproxy key to a set of HTTP methods so a read-only integration can be handed a key that cannot write. The provider had no way to express it, so those roles could not be managed from `terraform-vault`.

## How

- Adds an optional `methods` set attribute to `arrstack_secret_backend_role`, validated at plan time against `GET/HEAD/POST/PUT/PATCH/DELETE/OPTIONS` (upper case only, since the engine stores them upper-cased and a lower-case value would drift on every plan).
- Always writes `methods`: the engine only clears an existing scope when the key is present, so an omitted key would leave a stale scope behind.
- Reads an unrestricted role back as null rather than an empty set, so a config that omits `methods` shows no drift; a scope cleared out of band still surfaces as a diff.
- Documents the attribute in the README and both example configs.
- Tests cover the write mapping (null and populated), the read-back cases (absent/empty/null/cleared), and the plan-time validator.

Dependency: engine plugin >= 0.2.0.
Reviewed-on: #3
Co-authored-by: unkin-agent <unkin-agent@unkin.net>
Co-committed-by: unkin-agent <unkin-agent@unkin.net>

internal/provider/resource_secret_backend_role_test.go

@@ -3,8 +3,13 @@ package provider
 import (
 	"context"
 	"encoding/json"
+	"sort"
 	"testing"
 
+	"github.com/hashicorp/terraform-plugin-framework/path"
+	"github.com/hashicorp/terraform-plugin-framework/resource"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/schema/validator"
 	"github.com/hashicorp/terraform-plugin-framework/types"
 )
 
@@ -39,6 +44,49 @@ func TestRoleDataOmitsUnsetTTLs(t *testing.T) {
 	}
 }
 
+func TestRoleDataSendsEmptyMethodsWhenNull(t *testing.T) {
+	// The engine only clears a method scope when the key is present, so an
+	// unset methods must still be written as an empty list.
+	m := secretBackendRoleModel{
+		Apps:    setOf(t, "sonarr"),
+		Methods: types.SetNull(types.StringType),
+		TTL:     types.Int64Null(),
+		MaxTTL:  types.Int64Null(),
+	}
+	data, diags := roleData(context.Background(), m)
+	if diags.HasError() {
+		t.Fatalf("roleData: %v", diags)
+	}
+	methods, ok := data["methods"].([]string)
+	if !ok {
+		t.Fatalf("methods = %#v, want an empty []string", data["methods"])
+	}
+	if len(methods) != 0 {
+		t.Errorf("methods = %v, want empty", methods)
+	}
+}
+
+func TestRoleDataIncludesMethods(t *testing.T) {
+	m := secretBackendRoleModel{
+		Apps:    setOf(t, "sonarr"),
+		Methods: setOf(t, "GET", "HEAD"),
+		TTL:     types.Int64Null(),
+		MaxTTL:  types.Int64Null(),
+	}
+	data, diags := roleData(context.Background(), m)
+	if diags.HasError() {
+		t.Fatalf("roleData: %v", diags)
+	}
+	methods, ok := data["methods"].([]string)
+	if !ok || len(methods) != 2 {
+		t.Fatalf("methods = %#v, want [GET HEAD]", data["methods"])
+	}
+	sort.Strings(methods)
+	if methods[0] != "GET" || methods[1] != "HEAD" {
+		t.Errorf("methods = %v, want [GET HEAD]", methods)
+	}
+}
+
 func TestRoleDataIncludesTTLs(t *testing.T) {
 	m := secretBackendRoleModel{
 		Apps:   setOf(t, "prowlarr"),
@@ -120,3 +168,104 @@ func TestApplyRoleDataZeroTTLLeavesNull(t *testing.T) {
 		t.Errorf("max_ttl = %v, want null", m.MaxTTL)
 	}
 }
+
+func TestApplyRoleDataMapsMethods(t *testing.T) {
+	// The engine upper-cases and sorts the method scope it stores.
+	role := map[string]interface{}{
+		"apps":    []interface{}{"sonarr"},
+		"methods": []interface{}{"GET", "HEAD"},
+	}
+	m := secretBackendRoleModel{
+		Methods: setOf(t, "HEAD", "GET"),
+		TTL:     types.Int64Null(),
+		MaxTTL:  types.Int64Null(),
+	}
+	if diags := applyRoleData(&m, role); diags.HasError() {
+		t.Fatalf("applyRoleData: %v", diags)
+	}
+	if !m.Methods.Equal(setOf(t, "GET", "HEAD")) {
+		t.Errorf("methods = %v, want {GET HEAD}", m.Methods)
+	}
+}
+
+func TestApplyRoleDataUnrestrictedMethodsStayNull(t *testing.T) {
+	// An unrestricted role reads back as an empty/absent list, which must not
+	// clobber a null config value into an empty set and show permanent drift.
+	for name, role := range map[string]map[string]interface{}{
+		"absent": {"apps": []interface{}{"sonarr"}},
+		"empty":  {"apps": []interface{}{"sonarr"}, "methods": []interface{}{}},
+		"null":   {"apps": []interface{}{"sonarr"}, "methods": nil},
+	} {
+		t.Run(name, func(t *testing.T) {
+			m := secretBackendRoleModel{
+				Methods: types.SetNull(types.StringType),
+				TTL:     types.Int64Null(),
+				MaxTTL:  types.Int64Null(),
+			}
+			if diags := applyRoleData(&m, role); diags.HasError() {
+				t.Fatalf("applyRoleData: %v", diags)
+			}
+			if !m.Methods.IsNull() {
+				t.Errorf("methods = %v, want null", m.Methods)
+			}
+		})
+	}
+}
+
+func TestApplyRoleDataClearedMethodsShowDrift(t *testing.T) {
+	// A scope removed out of band must land in state as empty, so the next plan
+	// proposes putting the configured methods back.
+	role := map[string]interface{}{"apps": []interface{}{"sonarr"}}
+	m := secretBackendRoleModel{
+		Methods: setOf(t, "GET"),
+		TTL:     types.Int64Null(),
+		MaxTTL:  types.Int64Null(),
+	}
+	if diags := applyRoleData(&m, role); diags.HasError() {
+		t.Fatalf("applyRoleData: %v", diags)
+	}
+	if m.Methods.IsNull() || len(m.Methods.Elements()) != 0 {
+		t.Errorf("methods = %v, want an empty set", m.Methods)
+	}
+}
+
+func TestRoleSchemaMethodsValidation(t *testing.T) {
+	ctx := context.Background()
+	var resp resource.SchemaResponse
+	NewSecretBackendRoleResource().(*secretBackendRoleResource).Schema(ctx, resource.SchemaRequest{}, &resp)
+
+	attr, ok := resp.Schema.Attributes["methods"].(schema.SetAttribute)
+	if !ok {
+		t.Fatalf("methods attribute = %#v, want a schema.SetAttribute", resp.Schema.Attributes["methods"])
+	}
+	if attr.IsRequired() || !attr.IsOptional() {
+		t.Errorf("methods should be optional, not required")
+	}
+	if len(attr.Validators) == 0 {
+		t.Fatal("methods should carry a value validator")
+	}
+
+	for _, tc := range []struct {
+		name    string
+		values  []string
+		wantErr bool
+	}{
+		{name: "allowed", values: []string{"GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"}},
+		{name: "unknown method", values: []string{"GET", "FETCH"}, wantErr: true},
+		{name: "lower case", values: []string{"get"}, wantErr: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			req := validator.SetRequest{
+				Path:        path.Root("methods"),
+				ConfigValue: setOf(t, tc.values...),
+			}
+			var vResp validator.SetResponse
+			for _, v := range attr.Validators {
+				v.ValidateSet(ctx, req, &vResp)
+			}
+			if got := vResp.Diagnostics.HasError(); got != tc.wantErr {
+				t.Errorf("validation error = %v, want %v (%v)", got, tc.wantErr, vResp.Diagnostics)
+			}
+		})
+	}
+}