bzdatasource

Documentation

Overview

bzdatasource provides abstractions that make it easier to write data sources for the BastionZero API.

Index

• type APIModel
• type BaseListDataSourceConfig
  • func (c *BaseListDataSourceConfig[T, T2]) Validate() error
• type BaseSingleDataSourceConfig
  • func (c *BaseSingleDataSourceConfig[T, T2]) Validate() error
• type ListDataSource
  • func NewListDataSource[T TFComputedModel, T2 APIModel](config *ListDataSourceConfig[T, T2]) ListDataSource
• type ListDataSourceConfig
• type ListDataSourceWithPractitionerParameters
  • func NewListDataSourceWithPractitionerParameters[T TFComputedModel, T2 TFNonComputedModel, T3 APIModel](config *ListDataSourceWithPractitionerParametersConfig[T, T2, T3]) ListDataSourceWithPractitionerParameters
• type ListDataSourceWithPractitionerParametersConfig
• type SingleDataSource
  • func NewSingleDataSource[T TFSingleDataSourceModel, T2 APIModel](config *SingleDataSourceConfig[T, T2]) SingleDataSource
• type SingleDataSourceConfig
• type SingleDataSourceWithTimeout
  • func NewSingleDataSourceWithTimeout[T TFSingleDataSourceModel, T2 APIModel](config *SingleDataSourceWithTimeoutConfig[T, T2]) SingleDataSourceWithTimeout
• type SingleDataSourceWithTimeoutConfig
• type TFComputedModel
• type TFNonComputedModel
• type TFSingleDataSourceModel

Types

type APIModel

type APIModel = interface{}

APIModel is a BastionZero API object struct.

type BaseListDataSourceConfig

type BaseListDataSourceConfig[T TFComputedModel, T2 APIModel] struct {
	// RecordSchema is the TF schema that models a single instance of the API
	// object. There should be a key for each field defined in TFComputedModel.
	// Required.
	RecordSchema map[string]schema.Attribute

	// ResultAttributeName is the name of the TF attribute in the data source
	// through which to expose a list of results. Cannot be the empty string.
	ResultAttributeName string

	// MetadataTypeName is the suffix to use for the name of the data source.
	// Optional. If not set, then ResultAttributeName is used.
	MetadataTypeName string

	// PrettyAttributeName is a descriptive name used for logging and
	// documentation purposes. Cannot be the empty string.
	PrettyAttributeName string

	// FlattenAPIModel takes a model returned from the ListAPIModels function
	// and converts it to a TF model
	FlattenAPIModel func(ctx context.Context, apiObject *T2) (*T, diag.Diagnostics)

	// Description is passed as the data source schema's Description field
	// during construction.
	Description string

	// MarkdownDescription is passed as the data source schema's
	// MarkdownDescription field during construction.
	MarkdownDescription string

	// DeprecationMessage is passed as the data source schema's
	// DepcrecationMessage field during construction.
	DeprecationMessage string
}

BaseListDataSourceConfig contains common options used for creating any type of ListDataSource data source.

func (*BaseListDataSourceConfig[T, T2]) Validate

func (c *BaseListDataSourceConfig[T, T2]) Validate() error

Validate checks for errors in the base list data source config and fills in required values that were not set

type BaseSingleDataSourceConfig

type BaseSingleDataSourceConfig[T TFSingleDataSourceModel, T2 APIModel] struct {
	// RecordSchema is the TF schema that models a single instance of the API
	// object. There should be a key for each field defined in
	// TFSingleDataSourceModel. Required.
	RecordSchema map[string]schema.Attribute

	// MetadataTypeName is the suffix to use for the name of the data source.
	// Cannot be the empty string.
	MetadataTypeName string

	// PrettyAttributeName is the name of the attribute used for logging and
	// documentation purposes. Cannot be the empty string.
	PrettyAttributeName string

	// FlattenAPIModel takes a model returned from the GetAPIModel function and
	// uses it to update the TF model.
	FlattenAPIModel func(ctx context.Context, apiObject *T2, tfModel *T) diag.Diagnostics

	// GetAPIModel returns a single API object on which the data source should
	// expose.
	GetAPIModel func(ctx context.Context, tfModel T, client *bastionzero.Client) (*T2, error)

	// Description is passed as the data source schema's Description field
	// during construction.
	Description string

	// MarkdownDescription is passed as the data source schema's
	// MarkdownDescription field during construction.
	MarkdownDescription string

	// DeprecationMessage is passed as the data source schema's
	// DepcrecationMessage field during construction.
	DeprecationMessage string
}

func (*BaseSingleDataSourceConfig[T, T2]) Validate

func (c *BaseSingleDataSourceConfig[T, T2]) Validate() error

Validate checks for errors in the base single data source config

type ListDataSource

type ListDataSource datasource.DataSourceWithConfigure

ListDataSource is a data source that calls a BastionZero API endpoint which returns a list of objects. It abstracts common, boilerplate code that typically accompanies a data source that exposes a list of items.

If the API endpoint takes in additional parameters, and you wish to expose these to the practitioner for configuration in the TF schema, then use bzdatasource.ListDataSourceWithPractitionerParameters instead.

func NewListDataSource

func NewListDataSource[T TFComputedModel, T2 APIModel](config *ListDataSourceConfig[T, T2]) ListDataSource

NewListDataSource creates a ListDataSource. The function panics if the config is invalid.

type ListDataSourceConfig

type ListDataSourceConfig[T TFComputedModel, T2 APIModel] struct {
	*BaseListDataSourceConfig[T, T2]

	// ListAPIModels returns all of the API models on which the data source
	// should expose.
	ListAPIModels func(ctx context.Context, client *bastionzero.Client) ([]T2, error)
}

ListDataSourceConfig is the configuration for a list data source. It represents the schema and operations needed to create the data source.

type ListDataSourceWithPractitionerParameters

type ListDataSourceWithPractitionerParameters datasource.DataSourceWithConfigure

ListDataSourceWithPractitionerParameters is a data source that calls a BastionZero API endpoint which returns a list of objects. It abstracts common, boilerplate code that typically accompanies a data source that exposes a list of items. Additionally, it provides support for practitioner provided attributes (either Required = true or Optional = true) that can be accessed before calling the BastionZero API endpoint.

If there are no extra practitioner parameters required to call the API endpoint, then use bzdatasource.ListDataSource instead.

func NewListDataSourceWithPractitionerParameters

func NewListDataSourceWithPractitionerParameters[T TFComputedModel, T2 TFNonComputedModel, T3 APIModel](config *ListDataSourceWithPractitionerParametersConfig[T, T2, T3]) ListDataSourceWithPractitionerParameters

NewListDataSourceWithPractitionerParameters creates a ListDataSourceWithPractitionerParameters. The function panics if the config is invalid.

type ListDataSourceWithPractitionerParametersConfig

type ListDataSourceWithPractitionerParametersConfig[T TFComputedModel, T2 TFNonComputedModel, T3 APIModel] struct {
	*BaseListDataSourceConfig[T, T3]

	// PractitionerParamsRecordSchema is the TF schema that models additional
	// user parameters that are passed to ListAPIModels. Required.
	PractitionerParamsRecordSchema map[string]schema.Attribute

	// ListAPIModels returns all of the API models on which the data source
	// should expose. practitionerParams are the practitioner parameters
	// retrieved from the TF schema.
	ListAPIModels func(ctx context.Context, practitionerParams T2, client *bastionzero.Client) ([]T3, error)
}

ListDataSourceWithPractitionerParametersConfig is the configuration for a list data source with practitioner parameters. It represents the schema and operations needed to create the data source.

type SingleDataSource

type SingleDataSource datasource.DataSourceWithConfigure

SingleDataSource is a data source that calls a BastionZero API endpoint which returns a single object. It abstracts common, boilerplate code that typically accompanies a data source that exposes a single item. It is assumed the TF model contains some identification attribute(s) and/or parameters that can be used when querying the BastionZero API.

func NewSingleDataSource

func NewSingleDataSource[T TFSingleDataSourceModel, T2 APIModel](config *SingleDataSourceConfig[T, T2]) SingleDataSource

NewSingleDataSource creates a SingleDataSource. The function panics if the config is invalid.

type SingleDataSourceConfig

type SingleDataSourceConfig[T TFSingleDataSourceModel, T2 APIModel] struct {
	*BaseSingleDataSourceConfig[T, T2]
}

SingleDataSourceConfig is the configuration for a single data source. It represents the schema and operations needed to create the data source.

type SingleDataSourceWithTimeout

type SingleDataSourceWithTimeout datasource.DataSourceWithConfigure

SingleDataSourceWithTimeout is a data source with operational semantics similar to bzdatasource.SingleDataSource. It additionally abstracts calling a BastionZero API endpoint many times until it returns a valid response to expose through the data source.

GetAPIModel() is called with exponential backoff until a result is returned, or a timeout occurs. The timeout can be configured by the practitioner. If the error is fatal and should short circuit, have GetAPIModel() return an error of type backoff.PermanentError.

func NewSingleDataSourceWithTimeout

func NewSingleDataSourceWithTimeout[T TFSingleDataSourceModel, T2 APIModel](config *SingleDataSourceWithTimeoutConfig[T, T2]) SingleDataSourceWithTimeout

NewSingleDataSourceWithTimeout creates a SingleDataSourceWithTimeout. The function panics if the config is invalid.

type SingleDataSourceWithTimeoutConfig

type SingleDataSourceWithTimeoutConfig[T TFSingleDataSourceModel, T2 APIModel] struct {
	*BaseSingleDataSourceConfig[T, T2]

	// DefaultTimeout to use if the practitioner does not specify a timeout in
	// the "timeouts" field.
	DefaultTimeout time.Duration
}

SingleDataSourceWithTimeoutConfig is the configuration for a single data source with timeout. It represents the schema and operations needed to create the data source.

type TFComputedModel

type TFComputedModel = interface{}

TFComputedModel is a struct that models a collection of TF schema attributes that are Computed (Optional and Required should both be set to false).

type TFNonComputedModel

type TFNonComputedModel = interface{}

TFNonComputedModel is a struct that models a collection of TF schema attributes that are not Computed (Computed should be set to false. Required or Optional can be set to True).

type TFSingleDataSourceModel

type TFSingleDataSourceModel = interface{}

TFSingleDataSourceModel is a struct that models a collection of TF schema attributes that can be a mix of Computed, Required, and Optional attributes.