hcldec: add ValidateFuncSpec

This adds ValidateFuncSpec, a new decoder Spec that allows one to add
custom validations to work with values at decode-time.

The validation is run on the value after the wrapped spec is applied to
the expression in question. Diagnostics are expected to be returned,
with the author having flexibility over whether or not they want to
specify a range; if one is not supplied, the range of the wrapped
expression is used.

Author: vancluever

hcldec/spec.go

@@ -1565,6 +1565,58 @@ func (s *TransformFuncSpec) sourceRange(content *hcl.BodyContent, blockLabels []
 	return s.Wrapped.sourceRange(content, blockLabels)
 }
 
+// ValidateFuncSpec is a spec that allows for extended
+// developer-defined validation. The validation function receives the
+// result of the wrapped spec.
+//
+// The Subject field of the returned Diagnostic is optional. If not
+// specified, it is automatically populated with the range covered by
+// the wrapped spec.
+//
+type ValidateFuncSpec struct {
+	Wrapped Spec
+	Func    func(value cty.Value) hcl.Diagnostics
+}
+
+func (s *ValidateFuncSpec) visitSameBodyChildren(cb visitFunc) {
+	cb(s.Wrapped)
+}
+
+func (s *ValidateFuncSpec) decode(content *hcl.BodyContent, blockLabels []blockLabel, ctx *hcl.EvalContext) (cty.Value, hcl.Diagnostics) {
+	wrappedVal, diags := s.Wrapped.decode(content, blockLabels, ctx)
+	if diags.HasErrors() {
+		// We won't try to run our function in this case, because it'll probably
+		// generate confusing additional errors that will distract from the
+		// root cause.
+		return cty.UnknownVal(s.impliedType()), diags
+	}
+
+	validateDiags := s.Func(wrappedVal)
+	// Auto-populate the Subject fields if they weren't set.
+	for i := range validateDiags {
+		if validateDiags[i].Subject == nil {
+			validateDiags[i].Subject = s.sourceRange(content, blockLabels).Ptr()
+		}
+	}
+
+	diags = append(diags, validateDiags...)
+	return wrappedVal, diags
+}
+
+func (s *ValidateFuncSpec) impliedType() cty.Type {
+	return s.Wrapped.impliedType()
+}
+
+func (s *ValidateFuncSpec) sourceRange(content *hcl.BodyContent, blockLabels []blockLabel) hcl.Range {
+	// We'll just pass through our wrapped range here, even though that's
+	// not super-accurate, because there's nothing better to return.
+	//
+	// Depending on the context that the validation function is built in,
+	// it may return a more accurate range, in which point this will not
+	// be used anyway.
+	return s.Wrapped.sourceRange(content, blockLabels)
+}
+
 // noopSpec is a placeholder spec that does nothing, used in situations where
 // a non-nil placeholder spec is required. It is not exported because there is
 // no reason to use it directly; it is always an implementation detail only.

hcldec/spec_test.go

@@ -1,6 +1,7 @@
 package hcldec
 
 import (
+	"fmt"
 	"reflect"
 	"testing"
 
@@ -26,6 +27,7 @@ var _ Spec = (*BlockLabelSpec)(nil)
 var _ Spec = (*DefaultSpec)(nil)
 var _ Spec = (*TransformExprSpec)(nil)
 var _ Spec = (*TransformFuncSpec)(nil)
+var _ Spec = (*ValidateFuncSpec)(nil)
 
 var _ attrSpec = (*AttrSpec)(nil)
 var _ attrSpec = (*DefaultSpec)(nil)
@@ -139,3 +141,69 @@ bar = barval
 		}
 	})
 }
+
+func TestValidateFuncSpec(t *testing.T) {
+	config := `
+foo = "invalid"
+`
+	f, diags := hclsyntax.ParseConfig([]byte(config), "", hcl.Pos{Line: 1, Column: 1})
+	if diags.HasErrors() {
+		t.Fatal(diags.Error())
+	}
+
+	expectRange := map[string]*hcl.Range{
+		"without_range": nil,
+		"with_range": &hcl.Range{
+			Filename: "foobar",
+			Start:    hcl.Pos{Line: 99, Column: 99},
+			End:      hcl.Pos{Line: 999, Column: 999},
+		},
+	}
+
+	for name := range expectRange {
+		t.Run(name, func(t *testing.T) {
+			spec := &ValidateFuncSpec{
+				Wrapped: &AttrSpec{
+					Name: "foo",
+					Type: cty.String,
+				},
+				Func: func(value cty.Value) hcl.Diagnostics {
+					if value.AsString() != "invalid" {
+						return hcl.Diagnostics{
+							&hcl.Diagnostic{
+								Severity: hcl.DiagError,
+								Summary:  "incorrect value",
+								Detail:   fmt.Sprintf("invalid value passed in: %s", value.GoString()),
+							},
+						}
+					}
+
+					return hcl.Diagnostics{
+						&hcl.Diagnostic{
+							Severity: hcl.DiagWarning,
+							Summary:  "OK",
+							Detail:   "validation called correctly",
+							Subject:  expectRange[name],
+						},
+					}
+				},
+			}
+
+			_, diags = Decode(f.Body, spec, nil)
+			if len(diags) != 1 ||
+				diags[0].Severity != hcl.DiagWarning ||
+				diags[0].Summary != "OK" ||
+				diags[0].Detail != "validation called correctly" {
+				t.Fatalf("unexpected diagnostics: %s", diags.Error())
+			}
+
+			if expectRange[name] == nil && diags[0].Subject == nil {
+				t.Fatal("returned diagnostic subject missing")
+			}
+
+			if expectRange[name] != nil && !reflect.DeepEqual(expectRange[name], diags[0].Subject) {
+				t.Fatalf("expected range %s, got range %s", expectRange[name], diags[0].Subject)
+			}
+		})
+	}
+}