tfsdk: Introduce new ProviderServer functions, deprecate existing (#294)

Reference: #22

Provider developers have a few reasons to directly need a tfprotov6.ProviderServer implementation:

- When implementing acceptance testing with terraform-plugin-sdk helper/resource.
- When using terraform-plugin-mux tf6muxserver.NewMuxServer().
- When using terraform-plugin-mux tf6to5server.DowngradeServer().

The current `NewProtocol6Server(Provider)` function enables these use cases, however the implementation is less than ergonomic for provider developers as a wrapping function is required in all cases:

```go
// helper/resource acceptance testing

resource.TestCase{
	ProtoV6ProviderFactories: map[string]func() (tfprotov6.ProviderServer, error){
		"example": func() (tfprotov6.ProviderServer, error) {
			return tfsdk.NewProtocol6Server(New()), nil
		},
	},
 // ...
}

// tf6muxserver.NewMuxServer()

providers := []func() tfprotov6.ProviderServer{
	func() tfprotov6.ProviderServer {
		return tfsdk.NewProtocol6Server(provider1.New())
	},
	func() tfprotov6.ProviderServer {
		return tfsdk.NewProtocol6Server(provider2.New())
	},
}

muxServer, err := tf6muxserver.NewMuxServer(ctx, providers...)

// tf6to5server.DowngradeServer()

downgradeServer, err := tf6to5server.DowngradeServer(ctx, func() tfprotov6.ProviderServer {
	return tfsdk.NewProtocol6Server(provider.New())
})
```

The new functions simplify these implementations and get provider developers closer to not directly importing terraform-plugin-go (with a few other targeted changes, such as type aliases), e.g.

```go
// helper/resource acceptance testing

resource.TestCase{
	ProtoV6ProviderFactories: map[string]func() (tfprotov6.ProviderServer, error){
		"example": tfsdk.NewProtocol6ProviderServerWithError(New()),
	},
 // ...
}

// tf6muxserver.NewMuxServer()

providers := []func() tfprotov6.ProviderServer{
	tfsdk.NewProtocol6ProviderServer(provider1.New()),
  tfsdk.NewProtocol6ProviderServer(provider2.New()),
}

muxServer, err := tf6muxserver.NewMuxServer(ctx, providers...)

// tf6to5server.DowngradeServer()

downgradeServer, err := tf6to5server.DowngradeServer(ctx, tfsdk.NewProtocol6ProviderServer(provider.New()))
```

This change prefers deprecation over straight replacement to give some lead time for various documentation updates across multiple projects.

The naming is less than ideal, however it feels necessary to remain generic instead of picking any particular details related to their current usage (e.g. "NewTestServer") as this can/will change over time. The "Protocol6" naming is important should a new major protocol version 7 be released, which this framework must support.

.changelog/pending.txt

@@ -0,0 +1,11 @@
+```release-note:note
+tfsdk: The `NewProtocol6Server()` function has been deprecated in preference of `NewProtocol6ProviderServer()` and `NewProtocol6ProviderServerWithError()` functions, which will simplify muxing and testing implementations. The `NewProtocol6Server()` function will be removed in an upcoming minor release before v1.0.0.
+```
+
+```release-note:enhancement
+tfsdk: Added `NewProtocol6ProviderServer()` function, which can be directly used with terraform-plugin-go and terraform-plugin-mux.
+```
+
+```release-note:enhancement
+tfsdk: Added `NewProtocol6ProviderServerWithError()` function, which can be directly used with terraform-plugin-sdk acceptance testing.
+```

tfsdk/serve.go

@@ -38,12 +38,39 @@ type ServeOpts struct {
 
 // NewProtocol6Server returns a tfprotov6.ProviderServer implementation based
 // on the passed Provider implementation.
+//
+// Deprecated: Use NewProtocol6ProviderServer instead. This will be removed
+// in an upcoming minor version before v1.0.0.
 func NewProtocol6Server(p Provider) tfprotov6.ProviderServer {
 	return &server{
 		p: p,
 	}
 }
 
+// Returns a protocol version 6 ProviderServer implementation based on the
+// given Provider and suitable for usage with the terraform-plugin-go
+// tf6server.Serve() function and various terraform-plugin-mux functions.
+func NewProtocol6ProviderServer(p Provider) func() tfprotov6.ProviderServer {
+	return func() tfprotov6.ProviderServer {
+		return &server{
+			p: p,
+		}
+	}
+}
+
+// Returns a protocol version 6 ProviderServer implementation based on the
+// given Provider and suitable for usage with the terraform-plugin-sdk
+// acceptance testing helper/resource.TestCase.ProtoV6ProviderFactories.
+//
+// The error return is not currently used, but it may be in the future.
+func NewProtocol6ProviderServerWithError(p Provider) (func() tfprotov6.ProviderServer, error) {
+	return func() tfprotov6.ProviderServer {
+		return &server{
+			p: p,
+		}
+	}, nil
+}
+
 // Serve serves a provider, blocking until the context is canceled.
 func Serve(ctx context.Context, providerFunc func() Provider, opts ServeOpts) error {
 	var tf6serverOpts []tf6server.ServeOpt

tfsdk/serve_test.go

@@ -16,6 +16,39 @@ import (
 	"github.com/hashicorp/terraform-plugin-go/tftypes"
 )
 
+func TestNewProtocol6ProviderServer(t *testing.T) {
+	provider := &testServeProvider{}
+
+	providerServerFunc := NewProtocol6ProviderServer(provider)
+	providerServer := providerServerFunc()
+
+	// Simple verification
+	_, err := providerServer.GetProviderSchema(context.Background(), &tfprotov6.GetProviderSchemaRequest{})
+
+	if err != nil {
+		t.Fatalf("unexpected error calling ProviderServer: %s", err)
+	}
+}
+
+func TestNewProtocol6ProviderServerWithError(t *testing.T) {
+	provider := &testServeProvider{}
+
+	providerServerFunc, err := NewProtocol6ProviderServerWithError(provider)
+
+	if err != nil {
+		t.Fatalf("unexpected error creating ProviderServer: %s", err)
+	}
+
+	providerServer := providerServerFunc()
+
+	// Simple verification
+	_, err = providerServer.GetProviderSchema(context.Background(), &tfprotov6.GetProviderSchemaRequest{})
+
+	if err != nil {
+		t.Fatalf("unexpected error calling ProviderServer: %s", err)
+	}
+}
+
 func TestServerCancelInFlightContexts(t *testing.T) {
 	t.Parallel()