Merge pull request #368 from hashicorp/diagnostics

Diagnostics Proposal

Author: appilon

diag/diagnostic.go

@@ -0,0 +1,112 @@
+package diag
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/hashicorp/go-cty/cty"
+)
+
+// Diagnostics is a collection of Diagnostic.
+//
+// Developers should append and build the list of diagnostics up until a fatal
+// error is reached, at which point they should return the Diagnostics to the
+// SDK.
+type Diagnostics []Diagnostic
+
+// HasError returns true is Diagnostics contains an instance of
+// Severity == Error.
+//
+// This helper aims to mimic the go error practices of if err != nil. After any
+// operation that returns Diagnostics, check that it HasError and bubble up the
+// stack.
+func (diags Diagnostics) HasError() bool {
+	for i := range diags {
+		if diags[i].Severity == Error {
+			return true
+		}
+	}
+	return false
+}
+
+// Diagnostic is a contextual message intended at outlining problems in user
+// configuration.
+//
+// It supports multiple levels of severity (Error or Warning), a short Summary
+// of the problem, an optional longer Detail message that can assist the user in
+// fixing the problem, as well as an AttributePath representation which
+// Terraform uses to indicate where the issue took place in the user's
+// configuration.
+//
+// A Diagnostic will typically be used to pinpoint a problem with user
+// configuration, however it can still be used to present warnings or errors
+// to the user without any AttributePath set.
+type Diagnostic struct {
+	// Severity indicates the level of the Diagnostic. Currently can be set to
+	// either Error or Warning
+	Severity Severity
+
+	// Summary is a short description of the problem, rendered above location
+	// information
+	Summary string
+
+	// Detail is an optional second message rendered below location information
+	// typically used to communicate a potential fix to the user.
+	Detail string
+
+	// AttributePath is a representation of the path starting from the root of
+	// block (resource, datasource, provider) under evaluation by the SDK, to
+	// the attribute that the Diagnostic should be associated to. Terraform will
+	// use this information to render information on where the problem took
+	// place in the user's configuration.
+	//
+	// It is represented with cty.Path, which is a list of steps of either
+	// cty.GetAttrStep (an actual attribute) or cty.IndexStep (a step with Key
+	// of cty.StringVal for map indexes, and cty.NumberVal for list indexes).
+	//
+	// PLEASE NOTE: While cty can support indexing into sets, the SDK and
+	// protocol currently do not. For any Diagnostic related to a schema.TypeSet
+	// or a child of that type, please terminate the path at the schema.TypeSet
+	// and opt for more verbose Summary and Detail to help guide the user.
+	//
+	// Validity of the AttributePath is currently the responsibility of the
+	// developer, Terraform should render the root block (provider, resource,
+	// datasource) in cases where the attribute path is invalid.
+	AttributePath cty.Path
+}
+
+// Validate ensures a valid Severity and a non-empty Summary are set.
+func (d Diagnostic) Validate() error {
+	var validSev bool
+	for _, sev := range severities {
+		if d.Severity == sev {
+			validSev = true
+			break
+		}
+	}
+	if !validSev {
+		return fmt.Errorf("invalid severity: %v", d.Severity)
+	}
+	if d.Summary == "" {
+		return errors.New("empty summary")
+	}
+	return nil
+}
+
+// FromErr will convert an error into a Diagnostic
+func FromErr(err error) Diagnostic {
+	return Diagnostic{
+		Severity: Error,
+		Summary:  err.Error(),
+	}
+}
+
+// Severity is an enum type marking the severity level of a Diagnostic
+type Severity int
+
+const (
+	Error Severity = iota
+	Warning
+)
+
+var severities = []Severity{Error, Warning}

helper/schema/diagnostic_test.go

@@ -0,0 +1,45 @@
+package schema
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/hashicorp/go-multierror"
+	"github.com/hashicorp/terraform-plugin-sdk/v2/diag"
+)
+
+type errorDiags diag.Diagnostics
+
+func (diags errorDiags) Errors() []error {
+	var es []error
+	for i := range diags {
+		if diags[i].Severity == diag.Error {
+			s := fmt.Sprintf("Error: %s", diags[i].Summary)
+			if diags[i].Detail != "" {
+				s = fmt.Sprintf("%s: %s", s, diags[i].Detail)
+			}
+			es = append(es, errors.New(s))
+		}
+	}
+	return es
+}
+
+func (diags errorDiags) Error() string {
+	return multierror.ListFormatFunc(diags.Errors())
+}
+
+type warningDiags diag.Diagnostics
+
+func (diags warningDiags) Warnings() []string {
+	var ws []string
+	for i := range diags {
+		if diags[i].Severity == diag.Warning {
+			s := fmt.Sprintf("Warning: %s", diags[i].Summary)
+			if diags[i].Detail != "" {
+				s = fmt.Sprintf("%s: %s", s, diags[i].Detail)
+			}
+			ws = append(ws, s)
+		}
+	}
+	return ws
+}

helper/schema/provider.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/hashicorp/go-multierror"
 
+	"github.com/hashicorp/terraform-plugin-sdk/v2/diag"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/internal/configs/configschema"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/terraform"
 )
@@ -58,7 +59,9 @@ type Provider struct {
 	ConfigureFunc ConfigureFunc
 
 	// ConfigureContextFunc is a function for configuring the provider. If the
-	// provider doesn't need to be configured, this can be omitted.
+	// provider doesn't need to be configured, this can be omitted. This function
+	// receives a context.Context that will cancel when Terraform sends a
+	// cancellation signal. This function can yield Diagnostics
 	ConfigureContextFunc ConfigureContextFunc
 
 	meta interface{}
@@ -77,7 +80,7 @@ type ConfigureFunc func(*ResourceData) (interface{}, error)
 // the subsequent resources as the meta parameter. This return value is
 // usually used to pass along a configured API client, a configuration
 // structure, etc.
-type ConfigureContextFunc func(context.Context, *ResourceData) (interface{}, error)
+type ConfigureContextFunc func(context.Context, *ResourceData) (interface{}, diag.Diagnostics)
 
 // InternalValidate should be called to validate the structure
 // of the provider.
@@ -179,29 +182,32 @@ func (p *Provider) GetSchema(req *terraform.ProviderSchemaRequest) (*terraform.P
 }
 
 // Validate is called once at the beginning with the raw configuration
-// (no interpolation done) and can return a list of warnings and/or
-// errors.
+// (no interpolation done) and can return diagnostics
 //
 // This is called once with the provider configuration only. It may not
 // be called at all if no provider configuration is given.
 //
 // This should not assume that any values of the configurations are valid.
 // The primary use case of this call is to check that required keys are
 // set.
-func (p *Provider) Validate(c *terraform.ResourceConfig) ([]string, []error) {
+func (p *Provider) Validate(c *terraform.ResourceConfig) diag.Diagnostics {
 	if err := p.InternalValidate(); err != nil {
-		return nil, []error{fmt.Errorf(
-			"Internal validation of the provider failed! This is always a bug\n"+
-				"with the provider itself, and not a user issue. Please report\n"+
-				"this bug:\n\n%s", err)}
+		return []diag.Diagnostic{
+			{
+				Severity: diag.Error,
+				Summary:  "InternalValidate",
+				Detail: fmt.Sprintf("Internal validation of the provider failed! This is always a bug\n"+
+					"with the provider itself, and not a user issue. Please report\n"+
+					"this bug:\n\n%s", err),
+			},
+		}
 	}
 
 	return schemaMap(p.Schema).Validate(c)
 }
 
 // ValidateResource is called once at the beginning with the raw
-// configuration (no interpolation done) and can return a list of warnings
-// and/or errors.
+// configuration (no interpolation done) and can return diagnostics.
 //
 // This is called once per resource.
 //
@@ -210,11 +216,15 @@ func (p *Provider) Validate(c *terraform.ResourceConfig) ([]string, []error) {
 // The primary use case of this call is to check that the required keys
 // are set and that the general structure is correct.
 func (p *Provider) ValidateResource(
-	t string, c *terraform.ResourceConfig) ([]string, []error) {
+	t string, c *terraform.ResourceConfig) diag.Diagnostics {
 	r, ok := p.ResourcesMap[t]
 	if !ok {
-		return nil, []error{fmt.Errorf(
-			"Provider doesn't support resource: %s", t)}
+		return []diag.Diagnostic{
+			{
+				Severity: diag.Error,
+				Summary:  fmt.Sprintf("Provider doesn't support resource: %s", t),
+			},
+		}
 	}
 
 	return r.Validate(c)
@@ -224,12 +234,13 @@ func (p *Provider) ValidateResource(
 // given. This is useful for setting things like access keys.
 //
 // This won't be called at all if no provider configuration is given.
-//
-// Configure returns an error if it occurred.
-func (p *Provider) Configure(ctx context.Context, c *terraform.ResourceConfig) error {
+func (p *Provider) Configure(ctx context.Context, c *terraform.ResourceConfig) diag.Diagnostics {
+
+	var diags diag.Diagnostics
+
 	// No configuration
 	if p.ConfigureFunc == nil && p.ConfigureContextFunc == nil {
-		return nil
+		return diags
 	}
 
 	sm := schemaMap(p.Schema)
@@ -238,26 +249,31 @@ func (p *Provider) Configure(ctx context.Context, c *terraform.ResourceConfig) e
 	// generate an intermediary "diff" although that is never exposed.
 	diff, err := sm.Diff(ctx, nil, c, nil, p.meta, true)
 	if err != nil {
-		return err
+		return append(diags, diag.FromErr(err))
 	}
 
 	data, err := sm.Data(nil, diff)
 	if err != nil {
-		return err
+		return append(diags, diag.FromErr(err))
 	}
 
-	var meta interface{}
-	if p.ConfigureContextFunc != nil {
-		meta, err = p.ConfigureContextFunc(ctx, data)
-	} else {
-		meta, err = p.ConfigureFunc(data)
+	if p.ConfigureFunc != nil {
+		meta, err := p.ConfigureFunc(data)
+		if err != nil {
+			return append(diags, diag.FromErr(err))
+		}
+		p.meta = meta
 	}
-	if err != nil {
-		return err
+	if p.ConfigureContextFunc != nil {
+		meta, ds := p.ConfigureContextFunc(ctx, data)
+		diags = append(diags, ds...)
+		if diags.HasError() {
+			return diags
+		}
+		p.meta = meta
 	}
 
-	p.meta = meta
-	return nil
+	return diags
 }
 
 // Resources returns all the available resource types that this provider
@@ -361,8 +377,7 @@ func (p *Provider) ImportState(
 }
 
 // ValidateDataSource is called once at the beginning with the raw
-// configuration (no interpolation done) and can return a list of warnings
-// and/or errors.
+// configuration (no interpolation done) and can return diagnostics.
 //
 // This is called once per data source instance.
 //
@@ -371,11 +386,15 @@ func (p *Provider) ImportState(
 // The primary use case of this call is to check that the required keys
 // are set and that the general structure is correct.
 func (p *Provider) ValidateDataSource(
-	t string, c *terraform.ResourceConfig) ([]string, []error) {
+	t string, c *terraform.ResourceConfig) diag.Diagnostics {
 	r, ok := p.DataSourcesMap[t]
 	if !ok {
-		return nil, []error{fmt.Errorf(
-			"Provider doesn't support data source: %s", t)}
+		return []diag.Diagnostic{
+			{
+				Severity: diag.Error,
+				Summary:  fmt.Sprintf("Provider doesn't support data source: %s", t),
+			},
+		}
 	}
 
 	return r.Validate(c)