Diagnostics Proposal

[appilon]

This PR implements diagnostics for validation, CRUD, and ConfigureContextFunc. There are breaking changes to some functions along the callstack but they are functions mostly considered "internal" despite being publicly exported.

Usage

Schema: map[string]*schema.Schema{
  "bar": {
    Type: schema.TypeMap,
    Required: true,
    ValidateDiagFunc: func(v interface{}, path cty.Path) diag.Diagnostics {
      // please build up a slice of diagnostics
      // the new signature passes you the cty.Path up to the attribute being validated
      // the SDK will automatically set the attribute path of all diagnostics to at least this point
      // therefore for primitive types, developers can leave the AttributePath unset
      // in the case of TypeMap, to have precise diagnostics, please provider either a relative path
      // or an absolute path to the key that has a diagnostic. 
      var diags diag.Diagnostics

      // set a relative path
      diags = append(diags, diag.Diagnostic{
        Severity: diag.Error,
        Summary: "error in map key",
        AttributePath: cty.Path{ cty.IndexStep{ Key: cty.StringVal("key_name") } },
      })

      // create the absolute path yourself with the passed in path
      diags = append(diags, diag.Diagnostic{
        Severity: diag.Error,
        Summary: "error in map key",
        AttributePath: append(path, cty.IndexStep{ Key: cty.StringVal("key_name")),
      })

      return diags
    }
  },
}

For diagnostics support in the other areas of the SDK (such as the context aware CRUD) the usage is similar except the developer is responsible for constructing and setting the path entirely (validation is unique in that the SDK drills down the schema)

TypeSet

Unfortunately schema.TypeSet cannot be represented as an attribute path with the current protocol. In the case of validation the path is truncated at that attribute, which will provide some context to the user but it is not perfect, err on the side of verbose wording for diagnostics that are a child of TypeSet.

We are still investigating having guardrails around this in the CRUD API so developers don't create invalid paths in general (relative to their schema definition). The situation isn't so bad though as Terraform will just render blank where the line and file info would have been (not great but also nonfatal)

[paultyng]

why is this is an Errorf inside the panic? Should this func just return an error?

[appilon]

I wanted to add the line that this should be considered a bug in the provider implementation, hence the interpolation/fmt. Wanted the errors coming from the diagnostic validation to be terse

[paultyng]

Temporarily converted to draft while we work out the cty stuff, don't want to accidentally merge this.

[ghost]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.