function: Initial provider defined functions implementation (#889)

Reference: hashicorp/terraform-plugin-go#351

The next versions of the plugin protocol (5.5/6.5) include support for provider defined functions. This change includes initial implementation of that support including:

- Temporarily pointing at terraform-plugin-go with provider function support (will be pointed at final terraform-plugin-go release before merge)
- New `function` package with all exposed Go types for provider developers to implement provider functions
- New `diag` package support for diagnostics with optional function argument information
- Implementation of new `GetFunctions` and `CallFunction` RPCs in the internal framework server, protocol 5/6 servers, and data handling between all layers
- Initial website documentation

This functionality will be released as technical preview without compatibility promises until Terraform 1.8 is generally available. Go and website documentation include additional callouts about the compatibility of this functionality.

Co-authored-by: Austin Valle <austinvalle@gmail.com>

.changes/unreleased/ENHANCEMENTS-20231211-125057.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'diag: Added `NewArgumentErrorDiagnostic()` and `NewArgumentWarningDiagnostic()`
+  functions, which create diagnostics with the function argument position set'
+time: 2023-12-11T12:50:57.570179-05:00
+custom:
+  Issue: "889"

.changes/unreleased/ENHANCEMENTS-20231211-125151.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'provider: Added `ProviderWithFunctions` interface for implementing provider
+  defined functions'
+time: 2023-12-11T12:51:51.441373-05:00
+custom:
+  Issue: "889"

.changes/unreleased/ENHANCEMENTS-20231211-125843.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'diag: Added `(Diagnostics).AddArgumentError()` and `(Diagnostics).AddArgumentWarning()`
+  methods for appending function argument diagnostics'
+time: 2023-12-11T12:58:43.277177-05:00
+custom:
+  Issue: "889"

.changes/unreleased/FEATURES-20231211-125122.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'function: New package for implementing provider defined functions'
+time: 2023-12-11T12:51:22.409392-05:00
+custom:
+  Issue: "889"

.changes/unreleased/NOTES-20231214-082931.yaml

@@ -0,0 +1,6 @@
+kind: NOTES
+body: Provider-defined function support is in technical preview and offered without
+  compatibility promises until Terraform 1.8 is generally available.
+time: 2023-12-14T08:29:31.188561-05:00
+custom:
+  Issue: "889"

diag/argument_error_diagnostic.go

@@ -0,0 +1,13 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package diag
+
+// NewArgumentErrorDiagnostic returns a new error severity diagnostic with the
+// given summary, detail, and function argument.
+func NewArgumentErrorDiagnostic(functionArgument int, summary string, detail string) DiagnosticWithFunctionArgument {
+	return withFunctionArgument{
+		Diagnostic:       NewErrorDiagnostic(summary, detail),
+		functionArgument: functionArgument,
+	}
+}

diag/argument_warning_diagnostic.go

@@ -0,0 +1,13 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package diag
+
+// NewArgumentWarningDiagnostic returns a new warning severity diagnostic with
+// the given summary, detail, and function argument.
+func NewArgumentWarningDiagnostic(functionArgument int, summary string, detail string) DiagnosticWithFunctionArgument {
+	return withFunctionArgument{
+		Diagnostic:       NewWarningDiagnostic(summary, detail),
+		functionArgument: functionArgument,
+	}
+}

diag/diagnostic.go

@@ -38,6 +38,21 @@ type Diagnostic interface {
 	Equal(Diagnostic) bool
 }
 
+// DiagnosticWithFunctionArgument is a diagnostic associated with a
+// function argument.
+//
+// This information is used to display contextual source configuration to
+// practitioners.
+type DiagnosticWithFunctionArgument interface {
+	Diagnostic
+
+	// FunctionArgument points to a specific function argument position.
+	//
+	// If present, this enables the display of source configuration context for
+	// supporting implementations such as Terraform CLI commands.
+	FunctionArgument() int
+}
+
 // DiagnosticWithPath is a diagnostic associated with an attribute path.
 //
 // This attribute information is used to display contextual source configuration

diag/diagnostics.go

@@ -13,6 +13,18 @@ import (
 // or consistent.
 type Diagnostics []Diagnostic
 
+// AddArgumentError adds a generic function argument error diagnostic to the
+// collection.
+func (diags *Diagnostics) AddArgumentError(position int, summary string, detail string) {
+	diags.Append(NewArgumentErrorDiagnostic(position, summary, detail))
+}
+
+// AddArgumentWarning adds a function argument warning diagnostic to the
+// collection.
+func (diags *Diagnostics) AddArgumentWarning(position int, summary string, detail string) {
+	diags.Append(NewArgumentWarningDiagnostic(position, summary, detail))
+}
+
 // AddAttributeError adds a generic attribute error diagnostic to the collection.
 func (diags *Diagnostics) AddAttributeError(path path.Path, summary string, detail string) {
 	diags.Append(NewAttributeErrorDiagnostic(path, summary, detail))

diag/diagnostics_test.go

@@ -12,6 +12,130 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/path"
 )
 
+func TestDiagnosticsAddArgumentError(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		diags    diag.Diagnostics
+		position int
+		summary  string
+		detail   string
+		expected diag.Diagnostics
+	}{
+		"nil-add": {
+			diags:    nil,
+			position: 0,
+			summary:  "one summary",
+			detail:   "one detail",
+			expected: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+			},
+		},
+		"add": {
+			diags: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
+			},
+			position: 0,
+			summary:  "three summary",
+			detail:   "three detail",
+			expected: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
+				diag.NewArgumentErrorDiagnostic(0, "three summary", "three detail"),
+			},
+		},
+		"duplicate": {
+			diags: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
+			},
+			position: 0,
+			summary:  "one summary",
+			detail:   "one detail",
+			expected: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
+			},
+		},
+	}
+
+	for name, tc := range testCases {
+		name, tc := name, tc
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			tc.diags.AddArgumentError(tc.position, tc.summary, tc.detail)
+
+			if diff := cmp.Diff(tc.diags, tc.expected); diff != "" {
+				t.Errorf("Unexpected response (+wanted, -got): %s", diff)
+			}
+		})
+	}
+}
+
+func TestDiagnosticsAddArgumentWarning(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		diags    diag.Diagnostics
+		position int
+		summary  string
+		detail   string
+		expected diag.Diagnostics
+	}{
+		"nil-add": {
+			diags:    nil,
+			position: 0,
+			summary:  "one summary",
+			detail:   "one detail",
+			expected: diag.Diagnostics{
+				diag.NewArgumentWarningDiagnostic(0, "one summary", "one detail"),
+			},
+		},
+		"add": {
+			diags: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
+			},
+			position: 0,
+			summary:  "three summary",
+			detail:   "three detail",
+			expected: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
+				diag.NewArgumentWarningDiagnostic(0, "three summary", "three detail"),
+			},
+		},
+		"duplicate": {
+			diags: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
+			},
+			position: 0,
+			summary:  "two summary",
+			detail:   "two detail",
+			expected: diag.Diagnostics{
+				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
+				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
+			},
+		},
+	}
+
+	for name, tc := range testCases {
+		name, tc := name, tc
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			tc.diags.AddArgumentWarning(tc.position, tc.summary, tc.detail)
+
+			if diff := cmp.Diff(tc.diags, tc.expected); diff != "" {
+				t.Errorf("Unexpected response (+wanted, -got): %s", diff)
+			}
+		})
+	}
+}
+
 func TestDiagnosticsAddAttributeError(t *testing.T) {
 	t.Parallel()
 

diag/with_function_argument.go

@@ -0,0 +1,54 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package diag
+
+var _ DiagnosticWithFunctionArgument = withFunctionArgument{}
+
+// withFunctionArgument wraps a diagnostic with function argument information.
+type withFunctionArgument struct {
+	Diagnostic
+
+	functionArgument int
+}
+
+// Equal returns true if the other diagnostic is wholly equivalent.
+func (d withFunctionArgument) Equal(other Diagnostic) bool {
+	o, ok := other.(withFunctionArgument)
+
+	if !ok {
+		return false
+	}
+
+	if d.functionArgument != o.functionArgument {
+		return false
+	}
+
+	if d.Diagnostic == nil {
+		return d.Diagnostic == o.Diagnostic
+	}
+
+	return d.Diagnostic.Equal(o.Diagnostic)
+}
+
+// FunctionArgument returns the diagnostic function argument.
+func (d withFunctionArgument) FunctionArgument() int {
+	return d.functionArgument
+}
+
+// WithFunctionArgument wraps a diagnostic with function argument information
+// or overwrites the function argument.
+func WithFunctionArgument(functionArgument int, d Diagnostic) DiagnosticWithFunctionArgument {
+	wp, ok := d.(withFunctionArgument)
+
+	if !ok {
+		return withFunctionArgument{
+			Diagnostic:       d,
+			functionArgument: functionArgument,
+		}
+	}
+
+	wp.functionArgument = functionArgument
+
+	return wp
+}