-
Notifications
You must be signed in to change notification settings - Fork 94
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
tfsdk: Migrate data source, provider, and resource types into new Go …
…packages Reference: #132 Reference: #365 Reference: #366 Since the framework's initial release, the `tfsdk` Go package has been a monolithic collection of various provider concepts, including but not limited to handling of data sources, providers, resources, schemas, schema data (such as `Config`, `Plan`, and `State`), and various other helpers. For framework maintainers, this monolithic package has made implementations difficult for certain enhancements, such as import cycles. For provider developers, this monolithic package has been difficult to navigate in the Go documentation. This change represents the first major provider coding paradigm shift to colocate related concepts into their own Go packages, starting with new top-level `datasource`, `provider`, and `resource` packages. This particular change and method (no deprecation period) was not desired, but it was unavoidable due to the interconnectedness of the `tfsdk` package and due to the amount of effort it would require to attempt to support both the old and new types. This change is necessary to complete before there are additional code compatibility promises added to this Go module, such as a version 1.0.0 release or release candidate. This type of change is not taken lightly, as it is quite disruptive for existing provider codebases. On the surface, this change may look fairly unbeneficial for provider developers other than the easier discoverability and reduced wordiness, however it is required to unblock other future refactoring and enhancement efforts in the framework. It is unclear at the time of writing whether splitting out the other concepts from the `tfsdk` package, such as schemas, will present the same issues. Regardless, any other major changes will be spread across releases. Provider developers should be able to update their code using find and replace operations using the tables below. To reduce framework maintainer review burden, all code migrations were lift and shift operations while most code and documentation updates were find and replace operations. | Prior tfsdk Package Type | New provider Package Type | | --- | --- | | `tfsdk.ConfigureProviderRequest` | `provider.ConfigureRequest` | | `tfsdk.ConfigureProviderResponse` | `provider.ConfigureResponse` | | `tfsdk.Provider` | `provider.Provider` | | `tfsdk.ProviderConfigValidator` | `provider.ConfigValidator` | | `tfsdk.ProviderWithConfigValidators` | `provider.ProviderWithConfigValidators` | | `tfsdk.ProviderWithProviderMeta` | `provider.ProviderWithMetaSchema` (note naming realignment) | | `tfsdk.ProviderWithValidateConfig` | `provider.ProviderWithValidateConfig` | | `tfsdk.ValidateProviderConfigRequest` | `provider.ValidateConfigRequest` | | `tfsdk.ValidateProviderConfigResponse` | `provider.ValidateConfigResponse` | The `DataSourceType` abstraction migrates to the `provider` package since it relates to data that must be populated before the provider is configured as well as being passed the `Provider` interface, which can be converted into a concrete Go type when creating a `DataSource`. Other data source concept types are migrated to a new `datasource` package. | Prior tfsdk Package Type | New provider Package Type | | --- | --- | | `tfsdk.DataSourceType` | `provider.DataSourceType` | | Prior tfsdk Package Type | New datasource Package Type | | --- | --- | | `tfsdk.DataSource` | `datasource.DataSource` | | `tfsdk.DataSourceConfigValidator` | `datasource.ConfigValidator` | | `tfsdk.DataSourceWithConfigValidators` | `datasource.DataSourceWithConfigValidators` | | `tfsdk.DataSourceWithValidateConfig` | `datasource.DataSourceWithValidateConfig` | | `tfsdk.ReadDataSourceRequest` | `datasource.ReadRequest` | | `tfsdk.ReadDataSourceResponse` | `datasource.ReadResponse` | | `tfsdk.ValidateDataSourceConfigRequest` | `datasource.ValidateConfigRequest` | | `tfsdk.ValidateDataSourceConfigResponse` | `datasource.ValidateConfigResponse` | The `ResourceType` abstraction migrates to the `provider` package since it relates to data that must be populated before the provider is configured as well as being passed the `Provider` interface, which can be converted into a concrete Go type when creating a `Resource`. Other resource concept types are migrated to a new `resource` package. Additionally, the `tfsdk.ResourceImportStatePassthroughID()` function has been migrated to `resource.ImportStatePassthroughID()`. | Prior tfsdk Package Type | New provider Package Type | | --- | --- | | `tfsdk.ResourceType` | `provider.ResourceType` | | Prior tfsdk Package Type | New resource Package Type | | --- | --- | | `tfsdk.CreateResourceRequest` | `resource.CreateRequest` | | `tfsdk.CreateResourceResponse` | `resource.CreateResponse` | | `tfsdk.DeleteResourceRequest` | `resource.DeleteRequest` | | `tfsdk.DeleteResourceResponse` | `resource.DeleteResponse` | | `tfsdk.ImportResourceStateRequest` | `resource.ImportStateRequest` | | `tfsdk.ImportResourceStateResponse` | `resource.ImportStateResponse` | | `tfsdk.ModifyResourcePlanRequest` | `resource.ModifyPlanRequest` | | `tfsdk.ModifyResourcePlanResponse` | `resource.ModifyPlanResponse` | | `tfsdk.ReadResourceRequest` | `resource.ReadRequest` | | `tfsdk.ReadResourceResponse` | `resource.ReadResponse` | | `tfsdk.Resource` | `resource.Resource` | | `tfsdk.ResourceConfigValidator` | `resource.ConfigValidator` | | `tfsdk.ResourceWithConfigValidators` | `resource.ResourceWithConfigValidators` | | `tfsdk.ResourceWithImportState` | `resource.ResourceWithImportState` | | `tfsdk.ResourceWithModifyPlan` | `resource.ResourceWithModifyPlan` | | `tfsdk.ResourceWithUpgradeState` | `resource.ResourceWithUpgradeState` | | `tfsdk.ResourceWithValidateConfig` | `resource.ResourceWithValidateConfig` | | `tfsdk.UpdateResourceRequest` | `resource.UpdateRequest` | | `tfsdk.UpdateResourceResponse` | `resource.UpdateResponse` | | `tfsdk.UpgradeResourceStateRequest` | `resource.UpgradeStateRequest` | | `tfsdk.UpgradeResourceStateResponse` | `resource.UpgradeStateResponse` | | `tfsdk.ValidateResourceConfigRequest` | `resource.ValidateConfigRequest` | | `tfsdk.ValidateResourceConfigResponse` | `resource.ValidateConfigResponse` |
- Loading branch information
Showing
162 changed files
with
2,261 additions
and
2,056 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
```release-note:feature | ||
datasource: New package, which colocates all data source implementation types from the `tfsdk` package | ||
``` | ||
|
||
```release-note:feature | ||
provider: New package, which colocates all provider implementation types from the `tfsdk` package | ||
``` | ||
|
||
```release-note:feature | ||
resource: New package, which colocates all resource implementation types from the `tfsdk` package | ||
``` | ||
|
||
```release-note:breaking-change | ||
tfsdk: Go types relating to data source handling have been migrated to the new `datasource` package. Consult the pull request description for a full listing of find-and-replace information. | ||
``` | ||
|
||
```release-note:breaking-change | ||
tfsdk: Go types relating to provider handling have been migrated to the new `provider` package. Consult the pull request description for a full listing of find-and-replace information. | ||
``` | ||
|
||
```release-note:breaking-change | ||
tfsdk: Go types relating to resource handling have been migrated to the new `resource` package. Consult the pull request description for a full listing of find-and-replace information. | ||
``` | ||
|
||
```release-note:breaking-change | ||
tfsdk: The `ResourceImportStatePassthroughID()` function has been moved to `resource.ImportStatePassthroughID()`. | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
package datasource | ||
|
||
import "context" | ||
|
||
// ConfigValidator describes reusable data source configuration validation functionality. | ||
type ConfigValidator interface { | ||
// Description describes the validation in plain text formatting. | ||
// | ||
// This information may be automatically added to data source plain text | ||
// descriptions by external tooling. | ||
Description(context.Context) string | ||
|
||
// MarkdownDescription describes the validation in Markdown formatting. | ||
// | ||
// This information may be automatically added to data source Markdown | ||
// descriptions by external tooling. | ||
MarkdownDescription(context.Context) string | ||
|
||
// ValidateDataSource performs the validation. | ||
// | ||
// This method name is separate from the provider.ConfigValidator | ||
// interface ValidateProvider method name and resource.ConfigValidator | ||
// interface ValidateResource method name to allow generic validators. | ||
ValidateDataSource(context.Context, ValidateConfigRequest, *ValidateConfigResponse) | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
package datasource | ||
|
||
import "context" | ||
|
||
// DataSource represents a data source instance. This is the core interface that | ||
// all data sources must implement. | ||
type DataSource interface { | ||
// Read is called when the provider must read data source values in | ||
// order to update state. Config values should be read from the | ||
// ReadRequest and new state values set on the ReadResponse. | ||
Read(context.Context, ReadRequest, *ReadResponse) | ||
} | ||
|
||
// DataSourceWithConfigValidators is an interface type that extends DataSource to include declarative validations. | ||
// | ||
// Declaring validation using this methodology simplifies implmentation of | ||
// reusable functionality. These also include descriptions, which can be used | ||
// for automating documentation. | ||
// | ||
// Validation will include ConfigValidators and ValidateConfig, if both are | ||
// implemented, in addition to any Attribute or Type validation. | ||
type DataSourceWithConfigValidators interface { | ||
DataSource | ||
|
||
// ConfigValidators returns a list of ConfigValidators. Each ConfigValidator's Validate method will be called when validating the data source. | ||
ConfigValidators(context.Context) []ConfigValidator | ||
} | ||
|
||
// DataSourceWithValidateConfig is an interface type that extends DataSource to include imperative validation. | ||
// | ||
// Declaring validation using this methodology simplifies one-off | ||
// functionality that typically applies to a single data source. Any | ||
// documentation of this functionality must be manually added into schema | ||
// descriptions. | ||
// | ||
// Validation will include ConfigValidators and ValidateConfig, if both are | ||
// implemented, in addition to any Attribute or Type validation. | ||
type DataSourceWithValidateConfig interface { | ||
DataSource | ||
|
||
// ValidateConfig performs the validation. | ||
ValidateConfig(context.Context, ValidateConfigRequest, *ValidateConfigResponse) | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
// Package datasource contains all interfaces, request types, and response | ||
// types for a data source implementation. | ||
package datasource |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,37 @@ | ||
package datasource | ||
|
||
import ( | ||
"github.com/hashicorp/terraform-plugin-framework/diag" | ||
"github.com/hashicorp/terraform-plugin-framework/tfsdk" | ||
) | ||
|
||
// ReadRequest represents a request for the provider to read a data | ||
// source, i.e., update values in state according to the real state of the | ||
// data source. An instance of this request struct is supplied as an argument | ||
// to the data source's Read function. | ||
type ReadRequest struct { | ||
// Config is the configuration the user supplied for the data source. | ||
// | ||
// This configuration may contain unknown values if a user uses | ||
// interpolation or other functionality that would prevent Terraform | ||
// from knowing the value at request time. | ||
Config tfsdk.Config | ||
|
||
// ProviderMeta is metadata from the provider_meta block of the module. | ||
ProviderMeta tfsdk.Config | ||
} | ||
|
||
// ReadResponse represents a response to a ReadRequest. An | ||
// instance of this response struct is supplied as an argument to the data | ||
// source's Read function, in which the provider should set values on the | ||
// ReadResponse as appropriate. | ||
type ReadResponse struct { | ||
// State is the state of the data source following the Read operation. | ||
// This field should be set during the resource's Read operation. | ||
State tfsdk.State | ||
|
||
// Diagnostics report errors or warnings related to reading the data | ||
// source. An empty slice indicates a successful operation with no | ||
// warnings or errors generated. | ||
Diagnostics diag.Diagnostics | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
package datasource | ||
|
||
import ( | ||
"github.com/hashicorp/terraform-plugin-framework/diag" | ||
"github.com/hashicorp/terraform-plugin-framework/tfsdk" | ||
) | ||
|
||
// ValidateConfigRequest represents a request to validate the | ||
// configuration of a data source. An instance of this request struct is | ||
// supplied as an argument to the DataSource ValidateConfig receiver method | ||
// or automatically passed through to each ConfigValidator. | ||
type ValidateConfigRequest struct { | ||
// Config is the configuration the user supplied for the data source. | ||
// | ||
// This configuration may contain unknown values if a user uses | ||
// interpolation or other functionality that would prevent Terraform | ||
// from knowing the value at request time. | ||
Config tfsdk.Config | ||
} | ||
|
||
// ValidateConfigResponse represents a response to a | ||
// ValidateConfigRequest. An instance of this response struct is | ||
// supplied as an argument to the DataSource ValidateConfig receiver method | ||
// or automatically passed through to each ConfigValidator. | ||
type ValidateConfigResponse struct { | ||
// Diagnostics report errors or warnings related to validating the data | ||
// source configuration. An empty slice indicates success, with no warnings | ||
// or errors generated. | ||
Diagnostics diag.Diagnostics | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.