list: add types for `ListResource` support #1150

bbasata · 2025-05-27T22:21:17Z

Description

This pull request adds a top-level list package. list.ListResource is the Framework concept that defines a list block type, just as ephemeral.EphemeralResource defines an ephemeral block type and resource.Resource defines a resource block type.

A list resource always returns instances of a single managed resource type. For example, a random_pet list resource can only return instances of a random_pet managed resource type.

A developer can choose to implement the list.ListResource interface with an existing resource.Resource. This is intended to allow for cohesion between list resource logic and with managed resource CRUD logic.

A developer can instead choose to implement the list.ListResource interface separately from an existing resource.Resource. This is intended to allow for decoupling list resource logic from managed resource CRUD logic.

To allow for response data that exceeds the client's or server's maximum gRPC message size, the Plugin Protocol specifies a stream response for the ListResource RPC. Accordingly, the handler's result type is named list.ListResourceStream and it includes an iterator function of type iter.Seq[ListResourceEvent].

Rollback Plan

If a change needs to be reverted, we will roll out an update to the code within 7 days.

Changes to Security Controls

None.

list/list_resource.go

bbasata · 2025-05-27T22:25:58Z

list/schema/schema.go

+
+package schema
+
+type Schema struct {


💭 Clearly, this is a (very) partial implementation of a schema type 😃 In the interest of small pull requests, I'd like to save the details for the next PR.

list/list_resource.go

bbasata · 2025-05-27T22:32:20Z

list/list_resource.go

+	// Metadata can satisfy both interfaces.
+	Metadata(context.Context, resource.MetadataRequest, *resource.MetadataResponse)
+
+	// ListResourceConfigSchema should return the schema for list blocks.


In ConfigValidators, we have the precedent of a comment about method naming, such as:

// This method name is separate from ConfigValidators in resource and other packages in // order to allow generic validators.

This method is not named Schema for a similar reason. To comment or not to comment?

bbasata · 2025-05-27T22:32:40Z

list/list_resource.go

+	ListResource
+
+	// ListResourceConfigValidators returns a list of functions which will all be performed during validation.
+	ListResourceConfigValidators(context.Context) []ConfigValidator


In ConfigValidators, we have the precedent of a comment about method naming, such as:

// This method name is separate from ConfigValidators in resource and other packages in // order to allow generic validators.

This method is not named ConfigValidators for a similar reason. To comment or not to comment?

Yeah it might be worth being a little more specific in what these validators are used for at some point (i.e. list config validation when used with terraform query), then point to the other method name for resource config validation.

Same for the other methods

👍 – will revisit the comments in a follow-up PR.

bbasata · 2025-05-27T22:32:51Z

list/list_resource.go

+	ListResource
+
+	// ValidateListResourceConfig performs the validation.
+	ValidateListResourceConfig(context.Context, ValidateConfigRequest, *ValidateConfigResponse)


In ConfigValidators, we have the precedent of a comment about method naming, such as:

// This method name is separate from ConfigValidators in resource and other packages in // order to allow generic validators.

This method is not named ValidateConfig for a similar reason. To comment or not to comment?

list/list_resource.go

bbasata · 2025-05-27T23:14:04Z

list/list_resource.go

+	// The method signature is intended to be compatible with the Metadata
+	// method signature in the Resource interface. One implementation of
+	// Metadata can satisfy both interfaces.
+	Metadata(context.Context, resource.MetadataRequest, *resource.MetadataResponse)


A trade-off of compatibility: a bit of overloading of resource.MetadataRequest and resource.MetadataResponse. I think it's ok. I'm also open to improving on this.

I think this makes sense, i briefly mentioned that you could share the interfaces internally if you wanted in our 1/1, but that would mean you couldn't write a descriptive package comment for the method, so not really a big deal to duplicate imo.

bbasata · 2025-05-27T23:14:31Z

list/list_resource.go

+	// signature is intended to be compatible with the Configure method
+	// signature in the Resource interface. One implementation of Configure can
+	// satisfy both interfaces.
+	Configure(context.Context, resource.ConfigureRequest, *resource.ConfigureResponse)


A trade-off of compatibility: a bit of overloading of resource.ConfigureRequest and resource.ConfigureResponse. I think it's ok. I'm also open to improving on this.

tfsdk/resource_object.go

list/list_resource.go

austinvalle

I am halfway between ListResource and List 😆 , left some thoughts. I do like the interface design in general 👍🏻

austinvalle · 2025-05-29T13:49:57Z

list/schema.go

+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package list


A thought about the package location. Since list is coupled to managed resource (i.e. can't list without some managed resource existing in the provider), should we move all of these packages under resource?

resource/list
resource/list/schema

😃 I started from resource and ended up in a top-level list package.

I took a cue from: an instance of a "list resource" corresponds to a "list block" in Terraform.

So from a config perspective, list feels okay at the level of resource and ephemeral. And the import paths feel simpler.

And we leave the door open for our understanding of list to evolve.

tfsdk/resource_object.go

austinvalle · 2025-05-29T13:52:44Z

tfsdk/resource_object.go

+		Schema:         c.Schema,
+		TerraformValue: c.Raw,
+	}
+}


A note for later, eventually we'll need some form of Set* methods here. Typically providers are always supplementing data, i.e., we already created the object, populated some config data in, the provider "sets" the other attributes in the state, then we return it to Terraform.

Here, it might be a little different, we are creating the objects from scratch, so maybe different helpers can assist with that.

austinvalle · 2025-05-29T13:59:54Z

list/list_resource.go

+	// The method signature is intended to be compatible with the Metadata
+	// method signature in the Resource interface. One implementation of
+	// Metadata can satisfy both interfaces.
+	Metadata(context.Context, resource.MetadataRequest, *resource.MetadataResponse)


I think this makes sense, i briefly mentioned that you could share the interfaces internally if you wanted in our 1/1, but that would mean you couldn't write a descriptive package comment for the method, so not really a big deal to duplicate imo.

list/list_resource.go

bbasata · 2025-05-29T14:42:37Z

Private is just data that can be passed around in memory and not referenced. If we don't have that in the protocol, then no need to add here. Provider meta shouldn't be applicable here and there are no client capabilities for this RPC yet. So none of them are applicable ATM 😃

✅ I've removed the TODO comment (012fb27).

bbasata · 2025-05-29T15:27:02Z

Should we call this just tfsdk.Resource? 🤔

I'm 👍 on this. Shipping it.

Would it be too far to say that ResourceObject == State?

I think: [1] yes, they are two names for the same "underlying type," [2] I'd like to de-duplicate if possible, [3] maybe they are not aliases – one should not be assignable to the other (var state State = resourceObject // 💭 ), and [4] maybe they should be able to evolve independently.

💭 What if we extract an unexported type?

type valueWithSchema {
    Raw ...
    Schema ...
}

func (v *valueWithSchema) Get(...) { ... }

type Resource {
    valueWithSchema
}

type State {
    valueWithSchema
}

list/list_resource.go

bbasata · 2025-05-29T16:11:23Z

I feel like even omitting Resource would also be fine here. ListSchema, IdentitySchema, Schema

For consistency within the list package, I lean toward keeping ListResource in names of things that define the behavior of "a ListResource". With the exception of the List method itself.

austinvalle · 2025-05-30T19:02:38Z

list/list_resource.go

+	ListResource
+
+	// ListResourceConfigValidators returns a list of functions which will all be performed during validation.
+	ListResourceConfigValidators(context.Context) []ConfigValidator


Yeah it might be worth being a little more specific in what these validators are used for at some point (i.e. list config validation when used with terraform query), then point to the other method name for resource config validation.

Same for the other methods

bbasata · 2025-05-30T20:21:41Z

No changelog entry for the moment. We'll write a feature-level changelog entry 🔜.

bbasata force-pushed the add-list-package branch from 0601f75 to e96088a Compare May 27, 2025 22:22

list: add types for ListResource support

d7f3133

bbasata force-pushed the add-list-package branch from e96088a to d7f3133 Compare May 27, 2025 23:08

bbasata commented May 28, 2025

View reviewed changes

bbasata marked this pull request as ready for review May 28, 2025 19:51

bbasata requested a review from a team as a code owner May 28, 2025 19:51

bbasata mentioned this pull request May 28, 2025

fwserver: add list resources to GetMetadata #1151

Merged

1 task

bbasata added this to the v1.16.0 milestone May 28, 2025

refactor: rename ListResourceResponse to ListResourceStream

35b15f6

bbasata commented May 28, 2025

View reviewed changes

list/list_resource.go Outdated Show resolved Hide resolved

austinvalle reviewed May 29, 2025

View reviewed changes

Resolve TODO comment

012fb27

Rename ResourceObject to Resource

c4ccf44

bbasata commented May 29, 2025

View reviewed changes

list/list_resource.go Outdated Show resolved Hide resolved

Rename ListResource method to List

16a2973

bbasata requested a review from austinvalle May 29, 2025 16:14

austinvalle approved these changes May 30, 2025

View reviewed changes

bbasata merged commit 6997cf5 into main May 30, 2025
35 checks passed

bbasata deleted the add-list-package branch May 30, 2025 20:21

bbasata mentioned this pull request Jun 9, 2025

Consider exposing Resource "add-on" interfaces as stand-alone interfaces #1159

Open

github-actions bot locked as resolved and limited conversation to collaborators Jun 30, 2025

list: add types for ListResource support #1150

list: add types for ListResource support #1150

Uh oh!

Conversation

bbasata commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Rollback Plan

Changes to Security Controls

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

austinvalle left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bbasata commented May 29, 2025

Uh oh!

bbasata commented May 29, 2025

Uh oh!

Uh oh!

bbasata commented May 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bbasata commented May 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

list: add types for `ListResource` support #1150

list: add types for `ListResource` support #1150

bbasata commented May 27, 2025 •

edited

Loading

austinvalle left a comment •

edited

Loading