Add ListResource RPC (#525)

* Add ListResource RPC

* Add trace logging for each event

* simplify

* Add examples/terraform-provider-primes

* lint

Author: bbasata

examples/terraform-provider-primes/README.md

@@ -0,0 +1,71 @@
+# terraform-provider-primes
+
+```bash
+$ TF_LOG_SDK_PROTO=trace TF_PLUGIN_MAGIC_COOKIE=[value] go run ./examples/terraform-provider-primes
+
+{"@level":"debug","@message":"plugin address","@timestamp":"2037-06-30T10:10:00.627659+04:00","address":"...","network":"unix"}
+Provider started. To attach Terraform CLI, set the TF_REATTACH_PROVIDERS environment variable with the following:
+
+	TF_REATTACH_PROVIDERS='{"terraform.io/playground/primes":{"Protocol":"grpc","ProtocolVersion":5,"Pid":...,"Test":true,"Addr":{"Network":"unix","String":"..."}}}'
+
+Writing reattach configuration to env file at path reattach.env
+
+$ grpcurl -plaintext $(examples/terraform-provider-primes/reattach.sh) list
+grpc.health.v1.Health
+grpc.reflection.v1.ServerReflection
+grpc.reflection.v1alpha.ServerReflection
+plugin.GRPCBroker
+plugin.GRPCController
+plugin.GRPCStdio
+tfplugin5.Provider
+
+$ grpcurl -plaintext $(examples/terraform-provider-primes/reattach.sh) tfplugin5.Provider.GetSchema
+{
+  "provider": {},
+  "listResourceSchemas": {
+    "prime": {
+      "block": {
+        "attributes": [
+          {
+            "name": "number",
+            "type": "Im51bWJlciI=",
+            "description": "The nth prime"
+          },
+          {
+            "name": "ordinal",
+            "type": "Im51bWJlciI=",
+            "description": "n"
+          }
+        ]
+      }
+    }
+  }
+}
+
+$ grpcurl -plaintext $(examples/terraform-provider-primes/reattach.sh) tfplugin5.Provider.ListResource
+{
+  "displayName": "primes[1]: 2",
+  "resourceObject": {
+    "msgpack": "gqZudW1iZXICp29yZGluYWwB"
+  }
+}
+{
+  "displayName": "primes[2]: 3",
+  "resourceObject": {
+    "msgpack": "gqZudW1iZXIDp29yZGluYWwC"
+  }
+}
+{
+  "displayName": "primes[3]: 5",
+  "resourceObject": {
+    "msgpack": "gqZudW1iZXIFp29yZGluYWwD"
+  }
+}
+{
+  "displayName": "primes[4]: 7",
+  "resourceObject": {
+    "msgpack": "gqZudW1iZXIHp29yZGluYWwE"
+  }
+}
+...
+```

examples/terraform-provider-primes/main.go

@@ -0,0 +1,21 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package main
+
+import (
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5/tf5server"
+)
+
+func main() {
+	providerFn := func() tfprotov5.ProviderServer {
+		return PrimeNumberProvider{}
+	}
+
+	serveOpts := []tf5server.ServeOpt{
+		tf5server.WithManagedDebug(),
+		tf5server.WithManagedDebugEnvFilePath(".env.reattach"),
+	}
+	tf5server.Serve("terraform.io/playground/primes", providerFn, serveOpts...) //nolint:errcheck
+}

examples/terraform-provider-primes/provider.go

@@ -0,0 +1,144 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+)
+
+var _ tfprotov5.ProviderServerWithListResource = PrimeNumberProvider{} //nolint:staticcheck
+
+type PrimeNumberProvider struct {
+}
+
+func (p PrimeNumberProvider) GetMetadata(ctx context.Context, request *tfprotov5.GetMetadataRequest) (*tfprotov5.GetMetadataResponse, error) {
+	return &tfprotov5.GetMetadataResponse{
+		ListResources: []tfprotov5.ListResourceMetadata{
+			{
+				TypeName: "prime",
+			},
+		},
+	}, nil
+}
+
+func (p PrimeNumberProvider) GetResourceIdentitySchemas(ctx context.Context, request *tfprotov5.GetResourceIdentitySchemasRequest) (*tfprotov5.GetResourceIdentitySchemasResponse, error) {
+	return &tfprotov5.GetResourceIdentitySchemasResponse{
+		IdentitySchemas: map[string]*tfprotov5.ResourceIdentitySchema{
+			"prime": {
+				IdentityAttributes: []*tfprotov5.ResourceIdentitySchemaAttribute{
+					{
+						Name:              "number",
+						Type:              tftypes.Number,
+						RequiredForImport: true,
+					},
+				},
+			},
+		},
+	}, nil
+}
+
+func (p PrimeNumberProvider) GetProviderSchema(ctx context.Context, request *tfprotov5.GetProviderSchemaRequest) (*tfprotov5.GetProviderSchemaResponse, error) {
+	return &tfprotov5.GetProviderSchemaResponse{
+		Provider: &tfprotov5.Schema{
+			Block: &tfprotov5.SchemaBlock{
+				Description:     "Prime Provider",
+				DescriptionKind: tfprotov5.StringKindPlain,
+			},
+		},
+		ResourceSchemas: map[string]*tfprotov5.Schema{
+			"prime": p.primeSchema(),
+		},
+		ListResourceSchemas: map[string]*tfprotov5.Schema{
+			"prime": p.primeSchema(),
+		},
+	}, nil
+}
+
+func (p PrimeNumberProvider) primeSchema() *tfprotov5.Schema {
+	return &tfprotov5.Schema{
+		Block: &tfprotov5.SchemaBlock{
+			Attributes: []*tfprotov5.SchemaAttribute{
+				{
+					Name:            "number",
+					Type:            tftypes.Number,
+					Description:     "The nth prime",
+					DescriptionKind: tfprotov5.StringKindPlain,
+					Optional:        true,
+				},
+				{
+					Name:            "ordinal",
+					Type:            tftypes.Number,
+					Description:     "n",
+					DescriptionKind: tfprotov5.StringKindPlain,
+					Optional:        true,
+				},
+			},
+		},
+	}
+}
+
+func (p PrimeNumberProvider) PrepareProviderConfig(ctx context.Context, request *tfprotov5.PrepareProviderConfigRequest) (*tfprotov5.PrepareProviderConfigResponse, error) {
+	return &tfprotov5.PrepareProviderConfigResponse{
+		PreparedConfig: request.Config,
+	}, nil
+}
+
+func (p PrimeNumberProvider) ConfigureProvider(ctx context.Context, request *tfprotov5.ConfigureProviderRequest) (*tfprotov5.ConfigureProviderResponse, error) {
+	return &tfprotov5.ConfigureProviderResponse{}, nil
+}
+
+func (p PrimeNumberProvider) convertToDynamicValue(number int, ordinal int) (tfprotov5.DynamicValue, error) {
+	typ := p.primeSchema().ValueType()
+	value := map[string]tftypes.Value{
+		"number":  tftypes.NewValue(tftypes.Number, number),
+		"ordinal": tftypes.NewValue(tftypes.Number, ordinal),
+	}
+
+	return tfprotov5.NewDynamicValue(typ, tftypes.NewValue(typ, value))
+}
+
+func (p PrimeNumberProvider) ListResource(ctx context.Context, request *tfprotov5.ListResourceRequest) (*tfprotov5.ListResourceServerStream, error) {
+	primes := []int{2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97}
+
+	results := func(push func(tfprotov5.ListResourceResult) bool) {
+		for i, prime := range primes {
+			ordinal := i + 1
+			displayName := fmt.Sprintf("primes[%d]: %d", ordinal, prime)
+
+			resourceObject, err := p.convertToDynamicValue(prime, ordinal)
+			if err != nil {
+				panic(err)
+			}
+
+			protoEv := tfprotov5.ListResourceResult{
+				DisplayName: displayName,
+				Resource:    &resourceObject,
+			}
+			if !push(protoEv) {
+				fmt.Println("let's stop here")
+				return
+			}
+
+			fmt.Println("1 second nap")
+			time.Sleep(1 * time.Second)
+		}
+	}
+
+	return &tfprotov5.ListResourceServerStream{
+		Results: results,
+	}, nil
+}
+
+func (p PrimeNumberProvider) ValidateListResourceConfig(ctx context.Context, request *tfprotov5.ValidateListResourceConfigRequest) (*tfprotov5.ValidateListResourceConfigResponse, error) {
+	return &tfprotov5.ValidateListResourceConfigResponse{}, nil
+}
+
+func (p PrimeNumberProvider) StopProvider(ctx context.Context, request *tfprotov5.StopProviderRequest) (*tfprotov5.StopProviderResponse, error) {
+	return &tfprotov5.StopProviderResponse{}, nil
+}

examples/terraform-provider-primes/provider_not_implemented.go

@@ -0,0 +1,74 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package main
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+)
+
+func (p PrimeNumberProvider) UpgradeResourceIdentity(ctx context.Context, request *tfprotov5.UpgradeResourceIdentityRequest) (*tfprotov5.UpgradeResourceIdentityResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) ValidateResourceTypeConfig(ctx context.Context, request *tfprotov5.ValidateResourceTypeConfigRequest) (*tfprotov5.ValidateResourceTypeConfigResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) UpgradeResourceState(ctx context.Context, request *tfprotov5.UpgradeResourceStateRequest) (*tfprotov5.UpgradeResourceStateResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) ReadResource(ctx context.Context, request *tfprotov5.ReadResourceRequest) (*tfprotov5.ReadResourceResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) PlanResourceChange(ctx context.Context, request *tfprotov5.PlanResourceChangeRequest) (*tfprotov5.PlanResourceChangeResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) ApplyResourceChange(ctx context.Context, request *tfprotov5.ApplyResourceChangeRequest) (*tfprotov5.ApplyResourceChangeResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) ImportResourceState(ctx context.Context, request *tfprotov5.ImportResourceStateRequest) (*tfprotov5.ImportResourceStateResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) MoveResourceState(ctx context.Context, request *tfprotov5.MoveResourceStateRequest) (*tfprotov5.MoveResourceStateResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) ValidateDataSourceConfig(ctx context.Context, request *tfprotov5.ValidateDataSourceConfigRequest) (*tfprotov5.ValidateDataSourceConfigResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) ReadDataSource(ctx context.Context, request *tfprotov5.ReadDataSourceRequest) (*tfprotov5.ReadDataSourceResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) CallFunction(ctx context.Context, request *tfprotov5.CallFunctionRequest) (*tfprotov5.CallFunctionResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) GetFunctions(ctx context.Context, request *tfprotov5.GetFunctionsRequest) (*tfprotov5.GetFunctionsResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) ValidateEphemeralResourceConfig(ctx context.Context, request *tfprotov5.ValidateEphemeralResourceConfigRequest) (*tfprotov5.ValidateEphemeralResourceConfigResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) OpenEphemeralResource(ctx context.Context, request *tfprotov5.OpenEphemeralResourceRequest) (*tfprotov5.OpenEphemeralResourceResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) RenewEphemeralResource(ctx context.Context, request *tfprotov5.RenewEphemeralResourceRequest) (*tfprotov5.RenewEphemeralResourceResponse, error) {
+	panic("not implemented")
+}
+
+func (p PrimeNumberProvider) CloseEphemeralResource(ctx context.Context, request *tfprotov5.CloseEphemeralResourceRequest) (*tfprotov5.CloseEphemeralResourceResponse, error) {
+	panic("not implemented")
+}

examples/terraform-provider-primes/reattach.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+
+source .env.reattach
+echo $TF_REATTACH_PROVIDERS | jq -r '.["terraform.io/playground/primes"].Addr.Network + "://" + .["terraform.io/playground/primes"].Addr.String'

tfprotov5/internal/fromproto/list_resource.go

@@ -8,6 +8,18 @@ import (
 	"github.com/hashicorp/terraform-plugin-go/tfprotov5/internal/tfplugin5"
 )
 
+func ListResourceRequest(in *tfplugin5.ListResource_Request) *tfprotov5.ListResourceRequest {
+	if in == nil {
+		return nil
+	}
+
+	return &tfprotov5.ListResourceRequest{
+		TypeName:        in.TypeName,
+		Config:          DynamicValue(in.Config),
+		IncludeResource: in.IncludeResourceObject,
+	}
+}
+
 func ValidateListResourceConfigRequest(in *tfplugin5.ValidateListResourceConfig_Request) *tfprotov5.ValidateListResourceConfigRequest {
 	if in == nil {
 		return nil

tfprotov5/internal/tf5serverlogging/downstream_request.go

@@ -24,6 +24,25 @@ func DownstreamRequest(ctx context.Context) context.Context {
 	return ctx
 }
 
+// DownstreamServerEvent generates the following logging:
+//
+//   - TRACE "Received downstream server event" log with time elapsed since
+//     request start and diagnostic severity counts
+//   - Per-diagnostic logs
+func DownstreamServerEvent(ctx context.Context, diagnostics diag.Diagnostics) {
+	eventFields := map[string]interface{}{
+		logging.KeyDiagnosticErrorCount:   diagnostics.ErrorCount(),
+		logging.KeyDiagnosticWarningCount: diagnostics.WarningCount(),
+	}
+
+	if requestStart, ok := ctx.Value(ContextKeyDownstreamRequestStartTime{}).(time.Time); ok {
+		eventFields[logging.KeyRequestDurationMs] = time.Since(requestStart).Milliseconds()
+	}
+
+	logging.ProtocolTrace(ctx, "Received downstream server event", eventFields)
+	diagnostics.Log(ctx)
+}
+
 // DownstreamResponse generates the following logging:
 //
 //   - TRACE "Received downstream response" log with request duration and

tfprotov5/internal/toproto/list_resource.go

@@ -18,6 +18,15 @@ func GetMetadata_ListResourceMetadata(in *tfprotov5.ListResourceMetadata) *tfplu
 	}
 }
 
+func ListResource_ListResourceEvent(in *tfprotov5.ListResourceResult) *tfplugin5.ListResource_Event {
+	return &tfplugin5.ListResource_Event{
+		DisplayName:    in.DisplayName,
+		ResourceObject: DynamicValue(in.Resource),
+		Identity:       ResourceIdentityData(in.Identity),
+		Diagnostic:     Diagnostics(in.Diagnostics),
+	}
+}
+
 func ValidateListResourceConfig_Response(in *tfprotov5.ValidateListResourceConfigResponse) *tfplugin5.ValidateListResourceConfig_Response {
 	if in == nil {
 		return nil