fwschema

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 13, 2022 License: MPL-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package fwschema implements shared logic for describing the structure, data types, and behaviors of framework data for data sources, providers, and resources.

Refer to the internal/fwschemadata package for logic built on values based on this schema information.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrPathInsideAtomicAttribute is used with AttributeAtPath is called
	// on a path that doesn't have a schema associated with it, because
	// it's an element, attribute, or block of a complex type, not a nested
	// attribute.
	ErrPathInsideAtomicAttribute = errors.New("path leads to element, attribute, or block of a schema.Attribute that has no schema associated with it")

	// ErrPathIsBlock is used with AttributeAtPath is called on a path is a
	// block, not an attribute. Use blockAtPath on the path instead.
	ErrPathIsBlock = errors.New("path leads to block, not an attribute")
)

Functions

func AttributesEqual added in v0.17.0 

func AttributesEqual(a, b Attribute) bool

AttributesEqual is a helper function to perform equality testing on two Attribute. Attribute Equal implementations should still compare the concrete types in addition to using this helper.

func BlocksEqual added in v0.17.0 

func BlocksEqual(a, b Block) bool

BlocksEqual is a helper function to perform equality testing on two Block. Attribute Equal implementations should still compare the concrete types in addition to using this helper.

func NestedAttributeObjectApplyTerraform5AttributePathStep added in v0.17.0 

func NestedAttributeObjectApplyTerraform5AttributePathStep(o NestedAttributeObject, step tftypes.AttributePathStep) (any, error)

NestedAttributeObjectApplyTerraform5AttributePathStep is a helper function to perform base tftypes.AttributePathStepper handling using the GetAttributes method. NestedAttributeObject implementations should still include custom type functionality in addition to using this helper.

func NestedAttributeObjectEqual added in v0.17.0 

func NestedAttributeObjectEqual(a, b NestedAttributeObject) bool

NestedAttributeObjectEqual is a helper function to perform base equality testing on two NestedAttributeObject. NestedAttributeObject implementations should still compare the concrete types and other custom functionality in addition to using this helper.

func NestedAttributeObjectType added in v0.17.0 

func NestedAttributeObjectType(o NestedAttributeObject) basetypes.ObjectTypable

NestedAttributeObjectType is a helper function to perform base type handling using the GetAttributes and GetBlocks methods. NestedAttributeObject implementations should still include custom type functionality in addition to using this helper.

func NestedBlockObjectApplyTerraform5AttributePathStep added in v0.17.0 

func NestedBlockObjectApplyTerraform5AttributePathStep(o NestedBlockObject, step tftypes.AttributePathStep) (any, error)

NestedBlockObjectApplyTerraform5AttributePathStep is a helper function to perform base tftypes.AttributePathStepper handling using the GetAttributes and GetBlocks methods. NestedBlockObject implementations should still include custom type functionality in addition to using this helper.

func NestedBlockObjectEqual added in v0.17.0 

func NestedBlockObjectEqual(a, b NestedBlockObject) bool

NestedBlockObjectEqual is a helper function to perform base equality testing on two NestedBlockObject. NestedBlockObject implementations should still compare the concrete types and other custom functionality in addition to using this helper.

func NestedBlockObjectType added in v0.17.0 

func NestedBlockObjectType(o NestedBlockObject) basetypes.ObjectTypable

NestedBlockObjectType is a helper function to perform base type handling using the GetAttributes and GetBlocks methods. NestedBlockObject implementations should still include custom type functionality in addition to using this helper.

func SchemaApplyTerraform5AttributePathStep added in v0.17.0 

func SchemaApplyTerraform5AttributePathStep(s Schema, step tftypes.AttributePathStep) (any, error)

SchemaApplyTerraform5AttributePathStep is a helper function to perform base tftypes.AttributePathStepper handling using the GetAttributes and GetBlocks methods.

func SchemaType added in v0.17.0 

func SchemaType(s Schema) attr.Type

SchemaType is a helper function to perform base type handling using the GetAttributes and GetBlocks methods.

func SchemaTypeAtPath added in v0.17.0 

func SchemaTypeAtPath(ctx context.Context, s Schema, p path.Path) (attr.Type, diag.Diagnostics)

SchemaTypeAtPath is a helper function to perform base type handling using the TypeAtTerraformPath method.

func SchemaTypeAtTerraformPath added in v0.17.0 

func SchemaTypeAtTerraformPath(ctx context.Context, s Schema, p *tftypes.AttributePath) (attr.Type, error)

SchemaTypeAtTerraformPath is a helper function to perform base type handling using the tftypes.AttributePathStepper interface.

Types

type Attribute 

type Attribute interface {
	// Implementations should include the tftypes.AttributePathStepper
	// interface methods for proper path and data handling.
	tftypes.AttributePathStepper

	// Equal should return true if the other attribute is exactly equivalent.
	Equal(o Attribute) bool

	// GetDeprecationMessage should return a non-empty string if an attribute
	// is deprecated. This is named differently than DeprecationMessage to
	// prevent a conflict with the tfsdk.Attribute field name.
	GetDeprecationMessage() string

	// GetDescription should return a non-empty string if an attribute
	// has a plaintext description. This is named differently than Description
	// to prevent a conflict with the tfsdk.Attribute field name.
	GetDescription() string

	// GetMarkdownDescription should return a non-empty string if an attribute
	// has a Markdown description. This is named differently than
	// MarkdownDescription to prevent a conflict with the tfsdk.Attribute field
	// name.
	GetMarkdownDescription() string

	// GetType should return the framework type of an attribute. This is named
	// differently than Type to prevent a conflict with the tfsdk.Attribute
	// field name.
	GetType() attr.Type

	// IsComputed should return true if the attribute configuration value is
	// computed. This is named differently than Computed to prevent a conflict
	// with the tfsdk.Attribute field name.
	IsComputed() bool

	// IsOptional should return true if the attribute configuration value is
	// optional. This is named differently than Optional to prevent a conflict
	// with the tfsdk.Attribute field name.
	IsOptional() bool

	// IsRequired should return true if the attribute configuration value is
	// required. This is named differently than Required to prevent a conflict
	// with the tfsdk.Attribute field name.
	IsRequired() bool

	// IsSensitive should return true if the attribute configuration value is
	// sensitive. This is named differently than Sensitive to prevent a
	// conflict with the tfsdk.Attribute field name.
	IsSensitive() bool
}

Attribute is the core interface required for implementing Terraform schema functionality that can accept a value. Refer to NestedAttribute for the additional interface that defines nested attributes.

Refer to the internal/fwschema/fwxschema package for optional interfaces that define framework-specific functionality, such a plan modification and validation.

func SchemaAttributeAtPath added in v0.17.0 

func SchemaAttributeAtPath(ctx context.Context, s Schema, p path.Path) (Attribute, diag.Diagnostics)

SchemaAttributeAtPath is a helper function to perform base type handling using the AttributeAtTerraformPath method.

func SchemaAttributeAtTerraformPath added in v0.17.0 

func SchemaAttributeAtTerraformPath(ctx context.Context, s Schema, p *tftypes.AttributePath) (Attribute, error)

SchemaAttributeAtTerraformPath is a helper function to perform base type handling using the tftypes.AttributePathStepper interface.

type Block 

type Block interface {
	// Implementations should include the tftypes.AttributePathStepper
	// interface methods for proper path and data handling.
	tftypes.AttributePathStepper

	// Equal should return true if the other block is exactly equivalent.
	Equal(o Block) bool

	// GetDeprecationMessage should return a non-empty string if an attribute
	// is deprecated. This is named differently than DeprecationMessage to
	// prevent a conflict with the tfsdk.Attribute field name.
	GetDeprecationMessage() string

	// GetDescription should return a non-empty string if an attribute
	// has a plaintext description. This is named differently than Description
	// to prevent a conflict with the tfsdk.Attribute field name.
	GetDescription() string

	// GetMarkdownDescription should return a non-empty string if an attribute
	// has a Markdown description. This is named differently than
	// MarkdownDescription to prevent a conflict with the tfsdk.Attribute field
	// name.
	GetMarkdownDescription() string

	// GetNestedObject should return the object underneath the block.
	// For single nesting mode, the NestedBlockObject can be generated from
	// the Block.
	GetNestedObject() NestedBlockObject

	// GetNestingMode should return the nesting mode of a block. This is named
	// differently than NestingMode to prevent a conflict with the tfsdk.Block
	// field name.
	GetNestingMode() BlockNestingMode

	// Type should return the framework type of a block.
	Type() attr.Type
}

Block is the core interface required for implementing Terraform schema functionality that structurally holds attributes and blocks. This is intended to be the first abstraction of tfsdk.Block functionality into data source, provider, and resource specific functionality.

Refer to the internal/fwschema/fwxschema package for optional interfaces that define framework-specific functionality, such a plan modification and validation.

Note that MaxItems and MinItems support, while defined in the Terraform protocol, is intentially not present. Terraform can only perform limited static analysis of blocks and errors generated occur before the provider is called for configuration validation, which means that practitioners do not get all configuration errors at the same time. Provider developers can implement validators to achieve the same validation functionality.

type BlockNestingMode 

type BlockNestingMode uint8

BlockNestingMode is an enum type of the ways attributes and blocks can be nested in a block. They can be a list or a set.

While the protocol and theoretically Terraform itself support map and group nesting modes, this framework intentionally only supports list, set, and single blocks as those other modes were not typically implemented or tested with Terraform since the older Terraform Plugin SDK did not support them. 

const (
	// BlockNestingModeUnknown is an invalid nesting mode, used to catch when a
	// nesting mode is expected and not set.
	BlockNestingModeUnknown BlockNestingMode = 0

	// BlockNestingModeList is for attributes that represent a list of objects,
	// with multiple instances of those attributes nested inside a list
	// under another attribute.
	BlockNestingModeList BlockNestingMode = 1

	// BlockNestingModeSet is for attributes that represent a set of objects,
	// with multiple, unique instances of those attributes nested inside a
	// set under another attribute.
	BlockNestingModeSet BlockNestingMode = 2

	// BlockNestingModeSingle is for attributes that represent a single object.
	// The object cannot be repeated in the practitioner configuration.
	//
	// While the framework implements support for this block nesting mode, it
	// is not thoroughly tested in production Terraform environments beyond the
	// resource timeouts block from the older Terraform Plugin SDK. Use single
	// nested attributes for new implementations instead.
	BlockNestingModeSingle BlockNestingMode = 3
)

type NestedAttribute added in v0.17.0 

type NestedAttribute interface {
	Attribute

	// GetNestedObject should return the object underneath the nested
	// attribute. For single nesting mode, the NestedAttributeObject can be
	// generated from the Attribute.
	GetNestedObject() NestedAttributeObject

	// GetNestingMode should return the nesting mode (list, map, set, or
	// single) of the nested attributes or left unset if this Attribute
	// does not represent nested attributes.
	GetNestingMode() NestingMode
}

NestedAttribute defines a schema attribute that contains nested attributes.

type NestedAttributeObject added in v0.17.0 

type NestedAttributeObject interface {
	tftypes.AttributePathStepper

	// Equal should return true if given NestedAttributeObject is equivalent.
	Equal(NestedAttributeObject) bool

	// GetAttributes should return the nested attributes of an attribute.
	GetAttributes() UnderlyingAttributes

	// Type should return the framework type of the object.
	Type() basetypes.ObjectTypable
}

NestedAttributeObject represents the Object inside a NestedAttribute. Refer to the fwxschema package for validation and plan modification extensions to this interface.

type NestedBlockObject added in v0.17.0 

type NestedBlockObject interface {
	tftypes.AttributePathStepper

	// Equal should return true if given NestedBlockObject is equivalent.
	Equal(NestedBlockObject) bool

	// GetAttributes should return the nested attributes of the object.
	GetAttributes() UnderlyingAttributes

	// GetBlocks should return the nested attributes of the object.
	GetBlocks() map[string]Block

	// Type should return the framework type of the object.
	Type() basetypes.ObjectTypable
}

NestedBlockObject represents the Object inside a Block. Refer to the fwxschema package for validation and plan modification extensions to this interface.

type NestingMode 

type NestingMode uint8

NestingMode is an enum type of the ways nested attributes can be nested in an attribute. They can be a list, a set, a map (with string keys), or they can be nested directly, like an object. 

const (
	// NestingModeUnknown is an invalid nesting mode, used to catch when a
	// nesting mode is expected and not set.
	NestingModeUnknown NestingMode = 0

	// NestingModeSingle is for attributes that represent a struct or
	// object, a single instance of those attributes directly nested under
	// another attribute.
	NestingModeSingle NestingMode = 1

	// NestingModeList is for attributes that represent a list of objects,
	// with multiple instances of those attributes nested inside a list
	// under another attribute.
	NestingModeList NestingMode = 2

	// NestingModeSet is for attributes that represent a set of objects,
	// with multiple, unique instances of those attributes nested inside a
	// set under another attribute.
	NestingModeSet NestingMode = 3

	// NestingModeMap is for attributes that represent a map of objects,
	// with multiple instances of those attributes, each associated with a
	// unique string key, nested inside a map under another attribute.
	NestingModeMap NestingMode = 4
)

type Schema 

type Schema interface {
	// Implementations should include the tftypes.AttributePathStepper
	// interface methods for proper path and data handling.
	tftypes.AttributePathStepper

	// AttributeAtPath should return the Attribute at the given path or return
	// an error.
	AttributeAtPath(context.Context, path.Path) (Attribute, diag.Diagnostics)

	// AttributeAtTerraformPath should return the Attribute at the given
	// Terraform path or return an error.
	AttributeAtTerraformPath(context.Context, *tftypes.AttributePath) (Attribute, error)

	// GetAttributes should return the attributes of a schema. This is named
	// differently than Attributes to prevent a conflict with the tfsdk.Schema
	// field name.
	GetAttributes() map[string]Attribute

	// GetBlocks should return the blocks of a schema. This is named
	// differently than Blocks to prevent a conflict with the tfsdk.Schema
	// field name.
	GetBlocks() map[string]Block

	// GetDeprecationMessage should return a non-empty string if a schema
	// is deprecated. This is named differently than DeprecationMessage to
	// prevent a conflict with the tfsdk.Schema field name.
	GetDeprecationMessage() string

	// GetDescription should return a non-empty string if a schema has a
	// plaintext description. This is named differently than Description
	// to prevent a conflict with the tfsdk.Schema field name.
	GetDescription() string

	// GetMarkdownDescription should return a non-empty string if a schema has
	// a Markdown description. This is named differently than
	// MarkdownDescription to prevent a conflict with the tfsdk.Schema field
	// name.
	GetMarkdownDescription() string

	// GetVersion should return the version of a schema. This is named
	// differently than Version to prevent a conflict with the tfsdk.Schema
	// field name.
	GetVersion() int64

	// Type should return the framework type of the schema.
	Type() attr.Type

	// TypeAtPath should return the framework type of the Attribute at the
	// the given path or return an error.
	TypeAtPath(context.Context, path.Path) (attr.Type, diag.Diagnostics)

	// AttributeTypeAtPath should return the framework type of the Attribute at
	// the given Terraform path or return an error.
	TypeAtTerraformPath(context.Context, *tftypes.AttributePath) (attr.Type, error)
}

Schema is the core interface required for data sources, providers, and resources.

type UnderlyingAttributes 

type UnderlyingAttributes map[string]Attribute

UnderlyingAttributes represents attributes under a nested attribute.

func (UnderlyingAttributes) ApplyTerraform5AttributePathStep 

func (u UnderlyingAttributes) ApplyTerraform5AttributePathStep(step tftypes.AttributePathStep) (any, error)

ApplyTerraform5AttributePathStep performs an AttributeName step on the underlying attributes or returns an error.

func (UnderlyingAttributes) Equal added in v0.17.0 

func (u UnderlyingAttributes) Equal(o UnderlyingAttributes) bool

Equal returns true if all underlying attributes are equal.

func (UnderlyingAttributes) Type 

func (u UnderlyingAttributes) Type() basetypes.ObjectTypable

Type returns the framework type of the underlying attributes.

Source Files

View all Source files

Directories

Path Synopsis
Package fwxschema implements extra framework-based schema functionality on top of base Terraform attribute functionality.
 Package fwxschema implements extra framework-based schema functionality on top of base Terraform attribute functionality.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.