Documentation
¶
Overview ¶
Package helper is the shared utility package for resources/data sources on the terraform-plugin-framework side. It centralises common type conversions, retries, error normalisation and the timeouts block declaration so that individual resources do not re-implement them and drift apart in behaviour.
This package lives under `tencentcloud/framework/internal/`, where Go's `internal/` visibility rule limits imports to the `tencentcloud/framework/...` subtree. It is path-isolated from the project's existing SDKv2-facing `tencentcloud/internal/helper` (which depends on many SDKv2 types) so that neither symbols nor semantics can collide. The package depends only on framework standard types and the TencentCloud SDK error types.
Index ¶
- Variables
- func BoolPointerFromValue(v types.Bool) *bool
- func BoolValueOrNull(p *bool) types.Bool
- func Int64PointerFromValue(v types.Int64) *int64
- func Int64ValueFromUint(p *uint64) types.Int64
- func Int64ValueOrNull(p *int64) types.Int64
- func IsSDKErrorCode(err error, codes ...string) bool
- func IsTimeoutError(err error) bool
- func ParseTimeout(v types.String) (time.Duration, error)
- func RetryFramework[T any](ctx context.Context, timeout time.Duration, retryable RetryableErrorFn, ...) (T, error)
- func StringPointerFromValue(v types.String) *string
- func StringPointerValueOrNull(p *string) types.String
- func StringValueOrNull(s string) types.String
- func TimeoutOrDefault(v types.String, def time.Duration) time.Duration
- func TimeoutsBlock(stages ...string) schema.Block
- func WrapSDKError(summary string, err error) diag.Diagnostic
- type RetryableErrorFn
- type TimeoutsModel
Constants ¶
This section is empty.
Variables ¶
var ErrTimeoutNotSet = errors.New("timeout not set")
ErrTimeoutNotSet indicates that the user did not explicitly provide a timeout for the requested stage; callers should fall back to the resource's built-in default. (time.ParseDuration never returns this error.)
Functions ¶
func BoolPointerFromValue ¶
BoolPointerFromValue converts a types.Bool back to *bool.
func BoolValueOrNull ¶
BoolValueOrNull converts a *bool to types.Bool.
func Int64PointerFromValue ¶
Int64PointerFromValue converts a types.Int64 back to *int64.
func Int64ValueFromUint ¶
Int64ValueFromUint safely converts the *uint64 fields commonly seen in the TencentCloud SDK to types.Int64.
Note: when the source value exceeds math.MaxInt64 the conversion loses precision; however, business fields in TencentCloud (page size, quota, capacity, etc.) are not expected to surpass that ceiling for the foreseeable future, so this helper does not perform an overflow check. Callers must judge for themselves.
func Int64ValueOrNull ¶
Int64ValueOrNull converts an *int64 to types.Int64. Unlike the SDKv2 world, in framework a 0 is often a legal value, so this helper only performs nil handling at the pointer level.
func IsSDKErrorCode ¶
IsSDKErrorCode is the standard retryable predicate template: it returns true when err is a SDK error and its Code is contained in codes. A resource can use it inside RetryFramework like this:
helper.RetryFramework(ctx, timeout,
func(err error) bool {
return helper.IsSDKErrorCode(err,
"InternalError", "ResourceInUse", "FailedOperation")
},
func() (T, error) { ... })
func IsTimeoutError ¶
IsTimeoutError reports whether helper.RetryContext exited because of an overall timeout, so that callers can translate the timeout into a more user-friendly diagnostic.
func ParseTimeout ¶
ParseTimeout parses a duration string from a timeouts block field.
When the input is Null/Unknown or an empty string the function returns (0, ErrTimeoutNotSet) and the caller is expected to substitute the resource's built-in default. An invalid string surfaces the error from ParseDuration directly.
func RetryFramework ¶
func RetryFramework[T any]( ctx context.Context, timeout time.Duration, retryable RetryableErrorFn, fn func() (T, error), ) (T, error)
RetryFramework is the framework-flavoured equivalent of helper.Retry in the SDKv2 world.
Differences from SDKv2 helper.Retry:
- Callers no longer need to wrap *resource.RetryError manually; the business logic only returns (T, error) and the retryable predicate decides whether the error is retryable.
- It accepts ctx, so timeout and cancellation are governed by both ctx and the timeout argument.
Typical usage:
out, err := helper.RetryFramework(ctx, 30*time.Second, isResourceTransient,
func() (*sdk.DescribeFooResponse, error) {
return client.UseFooClient().DescribeFoo(req)
})
When err is nil it returns directly; when err is classified as retryable it enters the retry loop, otherwise it terminates immediately.
func StringPointerFromValue ¶
StringPointerFromValue converts a types.String back to *string:
- Null/Unknown returns nil (which usually means "do not send this field" when invoking the API).
- Otherwise it returns a pointer to the string value.
SDK request structs use *string heavily to express "optional, omitted". This helper keeps Create/Update code paths concise.
func StringPointerValueOrNull ¶
StringPointerValueOrNull converts a *string to types.String:
- A nil pointer returns types.StringNull().
- A non-nil pointer is preserved as types.StringValue("") even when the pointee is the empty string, because the very presence of the pointer means the API explicitly returned the field.
func StringValueOrNull ¶
StringValueOrNull safely converts a Go string to the framework's types.String:
- An empty string is treated as "value not present on the business side" and is returned as types.StringNull().
- A non-empty string is wrapped as types.StringValue.
In a resource Read, the common "the API did not return this field" scenario should produce types.StringNull() rather than an empty value; otherwise the plan comparison generates noisy diffs against Optional+Computed fields. If the empty string is itself a legal business value, do not use this helper — construct types.StringValue("") directly.
func TimeoutOrDefault ¶
TimeoutOrDefault falls back to def when ParseTimeout fails or no value is configured, suitable for one-line use at the entry point of CRUD methods:
timeout := helper.TimeoutOrDefault(plan.Timeouts.Create, 30*time.Minute)
func TimeoutsBlock ¶
TimeoutsBlock returns the generic timeouts block declaration used by framework resource schemas. It mirrors the user-facing semantics of the SDKv2 helper/schema Timeouts block:
resource "tencentcloud_xxx" "demo" {
timeouts {
create = "30m"
read = "10m"
update = "30m"
delete = "30m"
}
}
We deliberately avoid pulling in terraform-plugin-framework-timeouts as an external dependency to keep the vendor graph small (the project is sensitive to vendoring). All fields are Optional.
stages may be set to any of "create" / "read" / "update" / "delete" (lowercase). For instance, a pure data source only needs "read" while a resource typically uses create+read+update+delete. Stages that are not listed will not appear in the schema.
func WrapSDKError ¶
func WrapSDKError(summary string, err error) diag.Diagnostic
WrapSDKError translates an arbitrary error into a structured framework diag.Diagnostic.
When err is *sdkErrors.TencentCloudSDKError:
- Summary uses the supplied summary (the business-side context, e.g. "Failed to create foo").
- Detail includes Code, Message and RequestId so that troubleshooting and ticket filing are easier.
When err is any other type:
- Falls back to a generic error rendering; Detail contains only err.Error().
summary must not be empty; an empty summary is replaced with "TencentCloud API error" so the framework runtime does not reject the diagnostic as malformed.
Types ¶
type RetryableErrorFn ¶
RetryableErrorFn is the callback used by RetryFramework to classify an error as "retryable". Returning true means the error is transient and should be retried within the eventual-consistency window; false means the call should fail immediately.
Default (when nil is passed): every non-nil error is treated as non-retryable. Framework callers should supply their own predicate (for instance, white-listing specific TencentCloud SDK error codes).
type TimeoutsModel ¶
type TimeoutsModel struct {
Create types.String `tfsdk:"create"`
Read types.String `tfsdk:"read"`
Update types.String `tfsdk:"update"`
Delete types.String `tfsdk:"delete"`
}
TimeoutsModel is the Go counterpart of TimeoutsBlock. Resource models should embed it with the tag `tfsdk:"timeouts"`. Inside CRUD methods, use ParseTimeout to recover the time.Duration for a given stage.
Source Files