function: Initial provider defined functions implementation #889

bflad · 2023-12-11T17:47:50Z

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.

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 may be released as experimental without compatibility promises until the protocol and Terraform's handling of provider functions is finalized. In that situation, all Go and website documentation will include additional callouts about the experimental nature of the functionality.

…) methods

…ts/attributes The `AllowNullValue` parameter setting only prevents the value itself from being null, not elements/attributes.

…tribute value testing

…ment/attribute testing

…1460

bendbennett

LGTM 🚀

austinvalle

Overall looks awesome! I have some notes in the PR and then one general question.

In a use-case where you have a variadic parameter and you'd like to raise a diagnostic on one specific element..... Is that technically possible? I believe based on the protocol it should be? Should we document this if it is/isn't possible?

Like if I have a function that accepts one variadic IP Address string parameter, could I raise a diagnostic on the second argument:

provider::example::process_ips("127.0.0.1", "not-valid", "192.168.0.1")

internal/fwserver/server.go

austinvalle · 2023-12-14T20:50:19Z

internal/toproto5/getmetadata.go

@@ -18,16 +18,21 @@ func GetMetadataResponse(ctx context.Context, fw *fwserver.GetMetadataResponse)
 	}

 	protov6 := &tfprotov5.GetMetadataResponse{


nit: I know this was existing code, but just noticed, should probably be named protov5 or proto

I'll submit a followup PR to standardize these a little better to "protoResp" or something.

provider/provider.go

function/definition.go

website/docs/plugin/framework/functions/implementation.mdx

website/docs/plugin/framework/functions/parameters/index.mdx

website/docs/plugin/framework/functions/returns/index.mdx

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

bflad

Thank you for the thorough review, will poke at these items and get them fixed this afternoon or on Monday.

bflad · 2023-12-15T17:42:25Z

function/arguments_data.go

+		if fwreflect.IsGenericAttrValue(ctx, target) {
+			//nolint:forcetypeassert // Type assertion is guaranteed by the above `reflect.IsGenericAttrValue` function
+			*(target.(*attr.Value)) = attrValue
+			return nil
+		}


It should be continue -- will fix.

bflad · 2023-12-15T17:44:01Z

function/arguments_data_test.go

+				pointer((*bool)(nil)),
+				pointer("test"),
+			},
+		},


Will do. Will also create followup issue to do similar for tfsdk type handling where this logic came from as well, if they are missing them.

bflad · 2023-12-15T17:44:30Z

function/arguments_data_test.go

+			position: 0,
+			target:   new(*bool),
+			expected: pointer((*bool)(nil)),
+		},


Same comment as above.

bflad · 2023-12-15T17:47:14Z

function/list_parameter_test.go

+		// "CustomType": {
+		// 	parameter: function.ListParameter{
+		// 		CustomType: testtypes.ListType{},
+		// 	},
+		// 	expected: testtypes.ListType{},
+		// },


Sorry, I should have left a code comment, and its now been too long for me to exactly remember. Will take a peek as part of fixing other things here.

website/docs/plugin/framework/functions/documentation.mdx

website/docs/plugin/framework/functions/concepts.mdx

website/docs/plugin/framework/functions/implementation.mdx

…unctions

…ng zero-based and how to handle variadic parameters

bflad · 2023-12-15T20:58:29Z

In a use-case where you have a variadic parameter and you'd like to raise a diagnostic on one specific element..... Is that technically possible? I believe based on the protocol it should be? Should we document this if it is/isn't possible?

Indeed it is. 👍 Provider developers just need to consider the position consolidation done by the framework for the argument data. Its one of the hopefully few downsides to the variadic argument to list data handling approach, but I personally think the benefits (e.g. simplicity to still use (function.ArgumentsData).Get() and similarity to how Go itself implements variadic argument data) outweighs the consideration. Provider developers can also still opt to just raise a generic diagnostic without argument position.

Took a swing at documenting how that should be implemented in c4a1246. Please let me know if that is clear or if we should document that differently.

website/docs/plugin/framework/functions/implementation.mdx

austinvalle · 2023-12-15T23:06:44Z

I agree the list handling looks better and is more Go-like ™️. All the documentation updates look great, thanks!

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

…in-framework into functions

github-actions · 2024-01-19T02:09:06Z

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.

bflad added the enhancement New feature or request label Dec 11, 2023

bflad added this to the v1.5.0 milestone Dec 11, 2023

bflad requested a review from a team as a code owner December 11, 2023 17:47

bflad added 7 commits December 11, 2023 12:52

Update CHANGELOG for #889

113cc9f

diag: Add Diagnostics type AddArgumentError() and AddArgumentWarning(…

e5c1f6c

…) methods

website: Always recommend pointer types with collection/object elemen…

3735dc1

…ts/attributes The `AllowNullValue` parameter setting only prevents the value itself from being null, not elements/attributes.

website: Call out function argument collection/object null element/at…

316b82b

…tribute value testing

website: Further clarify function argument collection/object null ele…

4c51f47

…ment/attribute testing

deps: Update terraform-plugin-go@fb1d856be38c4fccc56fb61bcf6559aefb3a…

3ebd4f0

…1460

Add experimental callouts for functions

e68d4ea

bendbennett approved these changes Dec 14, 2023

View reviewed changes

bflad added 3 commits December 14, 2023 08:15

Clarify wording around function support compatibility

6ea401c

website: Add ConfigPlanCheck example for unknown testing

8adbb8d

Update CHANGELOG for #889

7bb93c4

bflad mentioned this pull request Dec 14, 2023

build(deps): Bump github.com/hashicorp/terraform-plugin-go from 0.19.1 to 0.20.0 #891

Merged

deps: Update terraform-plugin-go@v0.20.0

2ffc5d8

austinvalle approved these changes Dec 15, 2023

View reviewed changes

bflad and others added 3 commits December 15, 2023 12:50

Apply suggestions from code review

9979fe6

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

Update website/docs/plugin/framework/functions/index.mdx

2471135

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

Apply suggestions from code review

4d992e5

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

bflad commented Dec 15, 2023

View reviewed changes

jar-b mentioned this pull request Dec 15, 2023

[New Provider Function]: arn_parse and arn_build hashicorp/terraform-provider-aws#34952

Merged

bflad added 7 commits December 15, 2023 14:49

function: Add missing CustomType testing

f1aa0f6

internal: Add ArgumentsData unit testing with CustomType implementations

1c8f974

function: Do not return early with attr.Value in (ArgumentData).Get()

258e080

internal/fwserver: Fix errant functionTypes naming in Server

eec0477

internal/fwserver: Prevent false positives with GetMetadataResponse.F…

b2f1c6f

…unctions

function: Additional Go documentation details about argument data bei…

07a8699

…ng zero-based and how to handle variadic parameters

website: Document function variadic parameter implementation details

c4a1246

website: Use plain code fence language for markdown with frontmatter

9ebe290

austinvalle reviewed Dec 15, 2023

View reviewed changes

website/docs/plugin/framework/functions/implementation.mdx Outdated Show resolved Hide resolved

bflad and others added 5 commits December 18, 2023 09:53

Update website/docs/plugin/framework/functions/implementation.mdx

a93d54b

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

internal: Support xattr.TypeWithValidation for argument data

ed19111

Merge branch 'functions' of ssh://github.com/hashicorp/terraform-plug…

bff2f0a

…in-framework into functions

Merge branch 'main' into functions

bdb7fe6

Merge branch 'main' into functions

b785808

bflad merged commit 791e37b into main Dec 19, 2023
24 checks passed

bflad deleted the functions branch December 19, 2023 17:02

jar-b mentioned this pull request Jan 11, 2024

deps: bump terraform-plugin-framework to 1.5.0 hashicorp/terraform-provider-aws#35252

Merged

github-actions bot locked as resolved and limited conversation to collaborators Jan 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

function: Initial provider defined functions implementation #889

function: Initial provider defined functions implementation #889

bflad commented Dec 11, 2023 •

edited

Loading

bendbennett left a comment

austinvalle left a comment •

edited

Loading

austinvalle Dec 14, 2023

bflad Dec 15, 2023

bflad left a comment

bflad Dec 15, 2023

bflad Dec 15, 2023

bflad Dec 15, 2023

bflad Dec 15, 2023

bflad commented Dec 15, 2023

austinvalle commented Dec 15, 2023

github-actions bot commented Jan 19, 2024

		@@ -18,16 +18,21 @@ func GetMetadataResponse(ctx context.Context, fw *fwserver.GetMetadataResponse)
		}

		protov6 := &tfprotov5.GetMetadataResponse{

function: Initial provider defined functions implementation #889

function: Initial provider defined functions implementation #889

Conversation

bflad commented Dec 11, 2023 • edited Loading

bendbennett left a comment

Choose a reason for hiding this comment

austinvalle left a comment • edited Loading

Choose a reason for hiding this comment

austinvalle Dec 14, 2023

Choose a reason for hiding this comment

bflad Dec 15, 2023

Choose a reason for hiding this comment

bflad left a comment

Choose a reason for hiding this comment

bflad Dec 15, 2023

Choose a reason for hiding this comment

bflad Dec 15, 2023

Choose a reason for hiding this comment

bflad Dec 15, 2023

Choose a reason for hiding this comment

bflad Dec 15, 2023

Choose a reason for hiding this comment

bflad commented Dec 15, 2023

austinvalle commented Dec 15, 2023

github-actions bot commented Jan 19, 2024

bflad commented Dec 11, 2023 •

edited

Loading

austinvalle left a comment •

edited

Loading