Define Diagnostics type and helpers.

[paddycarver]

Module version

N/A

Use-cases

We want people to be able to return diagnostics and use them ergonomically, so we should provide some helper functions and ways to use them that makes it easier and less verbose to define diagnostics.

[paddycarver]

Do we want diagnostics to be an interface? Maybe a superset of the error interface? Maybe with a built-in implementation?

That would help address some of the validation stuff @bflad wants to do, e.g. being able to progressively enhance to support Not, etc. helpers on validation.

It would also allow providers to treat diagnostics more like errors, detecting on them, programming with them, allowing them to be more embedded in provider code rather than being for practitioner consumption only.

We could (in theory) have an interface something like this:

type Diagnostic interface {
  error

  DiagnosticSeverity() Severity
  DiagnosticSummary() string
  DiagnosticDetail() string
}

type DiagnosticWithPath interface {
  Diagnostic

  DiagnosticPath() tfsdk.Path
}

I think that would give the framework everything it needs to construct the tfprotov6.Diagnostic, and leaves us room to expand in the future if future protocol versions add more fields/whatever to diagnostics. It also means that diagnostics could be smuggled through things that are only meant to return errors, and detected (with fallback) on the other side.

[bflad]

Picking this up -- especially with recent Get/Set changeover to diagnostics, this is much more critical path now.

[paddycarver]

Do you want to start with a design doc, or do you want to head right into implementation?

[bflad]

I'm thinking design documentation if time allows, but happy to also just submit a very basic starter implementation, e.g.

package diag

type Diagnostic struct { /* ... */ }

type Diagnostics []Diagnostic

func (d Diagnostics) Append(...in Diagnostic)

func (d Diagnostics) HasError() bool

func (d Diagnostics) toTfprotov6Diagnostics() []*tfprotov6.Diagnostic

To unblock the current situation, until we have more time to noodle on whether interface types are a good idea (it seems valuable 😄 ) and write out design ideas.

[paddycarver]

My hot take is to do a timeboxed design document for, say, a week and let's figure out how to ship enough of an MVP to make it work if it doesn't look like the design document is getting consensus?

[github-actions]

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.