providerv1

type CustomVariableTypeDefinition struct {
	// The type of the custom variable type, prefixed by the namespace of the provider.
	// Example: "aws/ec2/instanceType" for the "aws" provider.
	Type string

	// A human-readable label for the custom variable type.
	// Example: "EC2 Instance Type" for the "aws/ec2/instanceType" custom variable type.
	Label string

	// A summary for the custom variable type that is not formatted
	// that can be used to render summaries in contexts that formatting is not supported.
	// This will be used in documentation and tooling when listing custom variable types.
	PlainTextSummary string

	// A summary for the custom variable type that can be formatted using markdown.
	// This will be used in documentation and tooling when listing custom variable types.
	FormattedSummary string

	// A description of the custom variable type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextDescription string

	// A description of the custom variable type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedDescription string

	// A list of examples that are not formatted that can be used to render examples
	// in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextExamples []string

	// A list of examples that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedExamples []string

	// A static map of options for values that are available for the variable type.
	// Each option is keyed by a label, essentially behaving as a runtime enum.
	// If OptionsFunc is defined, this static map will not be used.
	CustomVarTypeOptions map[string]*provider.CustomVariableTypeOption

	// A function that dynamically determines a map of key value pairs for options
	// that the user can choose from for a custom variable type.
	OptionsFunc func(
		ctx context.Context,
		input *provider.CustomVariableTypeOptionsInput,
	) (*provider.CustomVariableTypeOptionsOutput, error)
}

type DataSourceDefinition struct {
	// The type of the data source, prefixed by the namespace of the provider.
	// Example: "aws/lambda/function" for the "aws" provider.
	Type string

	// A human-readable label for the data source type.
	// This will be used in documentation and tooling.
	Label string

	// A summary of the data source type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextSummary string

	// A summary of the data source type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedSummary string

	// A description of the data source type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextDescription string

	// A description of the data source type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedDescription string

	// A list of plain text examples that can be used to
	// demonstrate how to use the data source.
	// This will be used in documentation and tooling.
	PlainTextExamples []string

	// A list of markdown examples that can be used to
	// demonstrate how to use the data source.
	// This will be used in documentation and tooling.
	MarkdownExamples []string

	// Schema definitions for each of the fields that can be exported
	// from a data source.
	Fields map[string]*provider.DataSourceSpecSchema

	// A static map of field names to schemas for filters
	// that can be used to filter in a data source query
	// to the provider.
	// If FilterFieldsFunc is provided, this static list will not be used.
	FilterFields map[string]*provider.DataSourceFilterSchema

	// A function that can be used to dynamically determine a list of fields
	// that can be used to filter in a data source query.
	FilterFieldsFunc func(
		ctx context.Context,
		input *provider.DataSourceGetFilterFieldsInput,
	) (*provider.DataSourceGetFilterFieldsOutput, error)

	// The function that deals with applying filters and retrieving the requested
	// data source from the upstream provider.
	FetchFunc func(
		ctx context.Context,
		input *provider.DataSourceFetchInput,
	) (*provider.DataSourceFetchOutput, error)

	// A function that can be used to carry validation for a data source that goes
	// beyond field schema and filter field validation.
	// When not provided, the plugin will return a result with an empty
	// list of diagnostics.
	CustomValidateFunc func(
		ctx context.Context,
		input *provider.DataSourceValidateInput,
	) (*provider.DataSourceValidateOutput, error)
}

type FunctionDefinition struct {

	// The definition that describes the signature of the function along with
	// useful information that can be used in tooling and documentation.
	Definition *function.Definition

	// Provides the behaviour for when the function plugin is called.
	CallFunc func(
		ctx context.Context,
		input *provider.FunctionCallInput,
	) (*provider.FunctionCallOutput, error)
}

type LinkDefinition struct {
	// an AWS Lambda function and an AWS DynamoDB table.
	// The type of the first resource in the link relationship.
	// (e.g. "aws/lambda/function").
	ResourceTypeA string

	// The type of resource B in the link relationship.
	// (e.g. "aws/dynamodb/table").
	ResourceTypeB string

	// The kind of link that contributes to the ordering of resources during deployment.
	// This can either be "hard" or "soft".
	// Hard links require the priority resource must exist before the dependent resource
	// can be created.
	// Soft links do not require either of the resources to exist before the other.
	Kind provider.LinkKind

	// A summary of the link type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextSummary string

	// A summary of the link type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedSummary string

	// A description of the link type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextDescription string

	// A description of the link type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedDescription string

	// A mapping of annotation names prefixed by resource type that
	// can be used to fine tune the behaviour of a link in a blueprint spec.
	// The format should be as follows:
	// {resourceType}::{annotationName} -> LinkAnnotationDefinition
	// e.g. "aws/lambda/function::aws.lambda.dynamodb.accessType" -> LinkAnnotationDefinition
	AnnotationDefinitions map[string]*provider.LinkAnnotationDefinition

	// The priority resource in the relationship based on the ordering of the resource
	// types.
	// For example in the link type "aws/lambda/function::aws/dynamodb/table",
	// if the priority resource should be "aws/lambda/function", then this field
	// should be set to `provider.LinkPriorityResourceA`.
	// If there is no priority resource, this field should be set to
	// `provider.LinkPriorityResourceNone`.
	// This will not be used if PriorityResourceFunc is provided.
	PriorityResource provider.LinkPriorityResource

	// A function that can be used to dynamically determine the priority resource
	// in the link relationship.
	PriorityResourceFunc func(
		ctx context.Context,
		input *provider.LinkGetPriorityResourceInput,
	) (*provider.LinkGetPriorityResourceOutput, error)

	// A function that details the changes that will be made when a deployment of the loaded blueprint
	// for the link between two resources.
	// Unlike resources, links do not map to a specification for a single deployable unit,
	// so link implementations must specify the changes that will be made across multiple resources.
	StageChangesFunc func(
		ctx context.Context,
		input *provider.LinkStageChangesInput,
	) (*provider.LinkStageChangesOutput, error)

	// A function that deals with applying the changes to the first of the two linked resources
	// for the creation or removal of a link between two resources.
	// The value of the `LinkData` field returned in the output will be combined
	// with the LinkData output from updating resource B and intermediary resources
	// to form the final LinkData that will be persisted in the state of the blueprint instance.
	// Parameters are passed into UpdateResourceA for extra context, blueprint variables will have already
	// been substituted at this stage and must be used instead of the passed in params argument
	// to ensure consistency between the staged changes that are reviewed and the deployment itself.
	UpdateResourceAFunc func(
		ctx context.Context,
		input *provider.LinkUpdateResourceInput,
	) (*provider.LinkUpdateResourceOutput, error)

	// A function that deals with applying the changes to the second of the two linked resources
	// for the creation or removal of a link between two resources.
	// The value of the `LinkData` field returned in the output will be combined
	// with the LinkData output from updating resource A and intermediary resources
	// to form the final LinkData that will be persisted in the state of the blueprint instance.
	// Parameters are passed into UpdateResourceB for extra context, blueprint variables will have already
	// been substituted at this stage and must be used instead of the passed in params argument
	// to ensure consistency between the staged changes that are reviewed and the deployment itself.
	UpdateResourceBFunc func(
		ctx context.Context,
		input *provider.LinkUpdateResourceInput,
	) (*provider.LinkUpdateResourceOutput, error)

	// A function that deals with creating, updating or deleting intermediary resources
	// that are required for the link between two resources.
	// This is called for both the creation and removal of a link between two resources.
	// The value of the `LinkData` field returned in the output will be combined
	// with the LinkData output from updating resource A and B
	// to form the final LinkData that will be persisted in the state of the blueprint instance.
	// Parameters are passed into UpdateIntermediaryResources for extra context, blueprint variables will have already
	// been substituted at this stage and must be used instead of the passed in params argument
	// to ensure consistency between the staged changes that are reviewed and the deployment itself.
	UpdateIntermediaryResourcesFunc func(
		ctx context.Context,
		input *provider.LinkUpdateIntermediaryResourcesInput,
	) (*provider.LinkUpdateIntermediaryResourcesOutput, error)
}

type ProviderPluginDefinition struct {
	ProviderNamespace        string
	ProviderConfigDefinition *core.ConfigDefinition
	Resources                map[string]provider.Resource
	DataSources              map[string]provider.DataSource
	Links                    map[string]provider.Link
	CustomVariableTypes      map[string]provider.CustomVariableType
	Functions                map[string]provider.Function
	ProviderRetryPolicy      *provider.RetryPolicy
}

type ResourceDefinition struct {
	// The type of the resource, prefixed by the namespace of the provider.
	// Example: "aws/lambda/function" for the "aws" provider.
	Type string

	// A human-readable label for the resource type.
	// This will be used in documentation and tooling.
	Label string

	// A summary of the resource type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextSummary string

	// A summary of the resource type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedSummary string

	// A description of the resource type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextDescription string

	// A description of the resource type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedDescription string

	// A list of plain text examples that can be used to
	// demonstrate how to use the resource.
	// This will be used in documentation and tooling.
	PlainTextExamples []string

	// A list of markdown examples that can be used to
	// demonstrate how to use the resource.
	// This will be used in documentation and tooling.
	FormattedExamples []string

	// The schema of the resource specification that comes under the `spec` field
	// of a resource in a blueprint.
	Schema *provider.ResourceDefinitionsSchema

	// Holds the name of the field in the resource schema that holds the third-party
	// ID of the resource.
	// This is used to resolve references to a resource in a blueprint
	// where only the name of the resource is specified.
	// For example, references such as `resources.processOrderFunction` or
	// `processOrderFunction` should resolve to the ID of the resource in the blueprint.
	// The ID field must be a top-level property of the resource spec schema.
	IDField string

	// DestroyBeforeCreate specifies whether the resource must be destroyed
	// before it can be created again.
	// In most cases, this should be false or not set, as where possible,
	// resources should be replaced with minimal disruption, as per a create-before-destroy
	// strategy.
	// This is useful for resources that will often need to be recreated with the same
	// user-defined unique name that are safe to destroy before creating a replacement.
	// This doesn't necessarily mean the resource will always be recreated successfully,
	// as some providers may not allow the use of the same name for a resource until a certain
	// period of time has passed since the resource was destroyed.
	//
	// To keep things simple for the practitioner, this is not something that can be set
	// in a blueprint spec, it is up to the developers of providers to set this
	// based on the nature of the resource and how critical it will be deemed for most use cases.
	DestroyBeforeCreate bool

	// Specifies whether this resource is expected to have a common use-case
	// as a terminal resource that does not link out to other resources.
	// This is useful for providing useful warnings to users about their blueprints
	// without overloading them with warnings for all resources that don't have any outbound
	// links that could have.
	// If CommonTerminalFunc is provided, this static value will not be used.
	CommonTerminal bool

	// A function that can be used to dynamically determine whether a resource is likely
	// to be a common terminal resource (does not link out to other resources).
	CommonTerminalFunc func(
		ctx context.Context,
		input *provider.ResourceIsCommonTerminalInput,
	) (*provider.ResourceIsCommonTerminalOutput, error)

	// A static list of resource types that this resource can link to.
	// If ResourceCanLinkToFunc is provided, this static list will not be used.
	ResourceCanLinkTo []string

	// A function that can be used to dynamically determine what resource types this resource
	// can link to.
	ResourceCanLinkToFunc func(
		ctx context.Context,
		input *provider.ResourceCanLinkToInput,
	) (*provider.ResourceCanLinkToOutput, error)

	// A static list of resource types that must be stabilised
	// before this resource can be deployed when they are dependencies
	// of this resource.
	// If StabilisedDependenciesFunc is provided, this static list will not be used.
	StabilisedDependencies []string

	// A function that can be used to dynamically determine what resource types must be stabilised
	// before this resource can be deployed.
	StabilisedDependenciesFunc func(
		ctx context.Context,
		input *provider.ResourceStabilisedDependenciesInput,
	) (*provider.ResourceStabilisedDependenciesOutput, error)

	// A function to retrieve the current state of the resource from the upstream system.
	// (e.g. fetch the state of an Lambda Function from AWS)
	GetExternalStateFunc func(
		ctx context.Context,
		input *provider.ResourceGetExternalStateInput,
	) (*provider.ResourceGetExternalStateOutput, error)

	// A function to create the resource in the upstream provider.
	CreateFunc func(
		ctx context.Context,
		input *provider.ResourceDeployInput,
	) (*provider.ResourceDeployOutput, error)

	// A function to update the resource in the upstream provider.
	UpdateFunc func(
		ctx context.Context,
		input *provider.ResourceDeployInput,
	) (*provider.ResourceDeployOutput, error)

	// A function to delete the resource in the upstream provider.
	DestroyFunc func(
		ctx context.Context,
		input *provider.ResourceDestroyInput,
	) error

	// A function to apply custom validation for a resource
	// that goes beyond validating against the resource spec schema which
	// the blueprint framework takes care of.
	// When not provided, the plugin will return a result with an empty list
	// of diagnostics.
	CustomValidateFunc func(
		ctx context.Context,
		input *provider.ResourceValidateInput,
	) (*provider.ResourceValidateOutput, error)

	// A function that is used to determine whether or not a resource is considered
	// to be in a stable state.
	// When not provided, `true` will be returned for the resource type
	// whenever the deploy engine checks whether or not a resource has
	// stabilised.
	StabilisedFunc func(
		ctx context.Context,
		input *provider.ResourceHasStabilisedInput,
	) (*provider.ResourceHasStabilisedOutput, error)
}