provider

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CapabilityFrom           = sdkprovider.CapabilityFrom
	CapabilityTransform      = sdkprovider.CapabilityTransform
	CapabilityValidation     = sdkprovider.CapabilityValidation
	CapabilityAuthentication = sdkprovider.CapabilityAuthentication
	CapabilityAction         = sdkprovider.CapabilityAction
)
View Source 
const (
	// SecretMask is the string used to redact secret values in logs and errors
	SecretMask = "***REDACTED***"
)

Variables

View Source 
var GlobalMetrics = &Metrics{enabled: false}

GlobalMetrics is the default metrics collector. Metrics collection is disabled by default; call Enable() to turn it on.

Functions

func AbsFromContext added in v0.6.0 

func AbsFromContext(ctx context.Context, path string) (string, error)

AbsFromContext resolves a relative path to an absolute path using the context working directory. Resolution priority:

  1. If the path is absolute, return it cleaned.
  2. If a working directory is set in context (via WithWorkingDirectory), use it.
  3. If a solution directory is set in context (via WithSolutionDirectory), use it. This ensures resolver-phase paths resolve relative to the solution file location.
  4. Fall back to filepath.Abs (which uses os.Getwd()).

Note: this function does NOT perform path containment/traversal validation. If the caller needs to restrict resolved paths within a specific directory, use ResolvePath (which validates containment for output directories) or perform additional checks after calling this function.

func BackupFromContext added in v0.6.0 

func BackupFromContext(ctx context.Context) (bool, bool)

BackupFromContext retrieves the backup flag from the context.

func ConflictStrategyFromContext added in v0.6.0 

func ConflictStrategyFromContext(ctx context.Context) (string, bool)

ConflictStrategyFromContext retrieves the conflict strategy from the context.

func Count 

func Count() int

Count returns the number of providers in the global registry.

func DryRunFromContext 

func DryRunFromContext(ctx context.Context) bool

DryRunFromContext retrieves the dry-run flag from the context. Defaults to false if not set.

func GetWorkingDirectory added in v0.6.0 

func GetWorkingDirectory(ctx context.Context) (string, error)

GetWorkingDirectory returns the effective working directory from the context. It checks the context for a logical working directory first (set via WithWorkingDirectory), then falls back to the process CWD via os.Getwd().

func Has 

func Has(name string) bool

Has checks if a provider is registered in the global registry.

func List 

func List() []string

List returns all provider names from the global registry.

func MaskValue 

func MaskValue(value any, isSecret bool) string

MaskValue redacts a value if it should be kept secret. This is useful for logging and error messages.

func OutputDirectoryFromContext added in v0.6.0 

func OutputDirectoryFromContext(ctx context.Context) (string, bool)

OutputDirectoryFromContext retrieves the output directory from the context.

func ParametersFromContext 

func ParametersFromContext(ctx context.Context) (map[string]any, bool)

ParametersFromContext retrieves the CLI parameters map from the context.

func Register 

func Register(p Provider) error

Register registers a provider in the global registry.

func ResetGlobalExecutor 

func ResetGlobalExecutor()

ResetGlobalExecutor resets the global executor to a new instance. This is primarily for testing purposes.

func ResetGlobalRegistry 

func ResetGlobalRegistry()

ResetGlobalRegistry clears the global registry. This is primarily for testing purposes.

func ResolvePath added in v0.6.0 

func ResolvePath(ctx context.Context, path string) (string, error)

ResolvePath resolves a filesystem path based on the current execution context.

When all of the following are true, the path is resolved against the output directory:

  • The path is relative
  • The execution mode is CapabilityAction
  • An output directory is set in the context

Otherwise, the path is resolved against the context working directory (set via WithWorkingDirectory), falling back to the process CWD when no context directory is set.

When resolving against an output directory, the result is validated to ensure it does not escape the output directory via parent traversal (e.g., "../../../etc/passwd").

func ResolverContextFromContext 

func ResolverContextFromContext(ctx context.Context) (map[string]any, bool)

ResolverContextFromContext retrieves the resolver context map from the context.

func SolutionDirectoryFromContext added in v0.8.0 

func SolutionDirectoryFromContext(ctx context.Context) (string, bool)

SolutionDirectoryFromContext retrieves the solution file's parent directory. Returns the directory path and true if found, empty string and false otherwise.

func ValidateDescriptor 

func ValidateDescriptor(desc *Descriptor) error

ValidateDescriptor validates that a Descriptor meets all requirements.

func ValidateDirectory added in v0.6.0 

func ValidateDirectory(dir string) (string, error)

ValidateDirectory resolves a directory path to an absolute path and validates that it exists and is a directory. Returns the resolved absolute path or an error.

func WithBackup added in v0.6.0 

func WithBackup(ctx context.Context, backup bool) context.Context

WithBackup returns a new context with the backup flag attached.

func WithConflictStrategy added in v0.6.0 

func WithConflictStrategy(ctx context.Context, strategy string) context.Context

WithConflictStrategy returns a new context with the conflict strategy attached.

func WithDryRun 

func WithDryRun(ctx context.Context, dryRun bool) context.Context

WithDryRun returns a new context with the dry-run flag set.

func WithExecutionMode 

func WithExecutionMode(ctx context.Context, mode Capability) context.Context

WithExecutionMode returns a new context with the specified execution mode (capability).

func WithIOStreams added in v0.4.0 

func WithIOStreams(ctx context.Context, streams *IOStreams) context.Context

WithIOStreams returns a new context with IO streams for provider terminal output.

func WithIterationContext 

func WithIterationContext(ctx context.Context, iterCtx *IterationContext) context.Context

WithIterationContext returns a new context with the iteration context.

func WithOutputDirectory added in v0.6.0 

func WithOutputDirectory(ctx context.Context, dir string) context.Context

WithOutputDirectory returns a new context with the output directory path attached.

func WithParameters 

func WithParameters(ctx context.Context, parameters map[string]any) context.Context

WithParameters returns a new context with the CLI parameters map.

func WithResolverContext 

func WithResolverContext(ctx context.Context, resolverContext map[string]any) context.Context

WithResolverContext returns a new context with the resolver context map.

func WithSolutionDirectory added in v0.8.0 

func WithSolutionDirectory(ctx context.Context, dir string) context.Context

WithSolutionDirectory returns a new context with the solution file's parent directory. When set, resolver-phase path resolution uses this as the base for relative paths instead of the process CWD, ensuring consistent behaviour between local and bundled execution.

func WithSolutionMetadata added in v0.6.0 

func WithSolutionMetadata(ctx context.Context, meta *SolutionMeta) context.Context

WithSolutionMetadata returns a new context with the solution metadata attached.

func WithWorkingDirectory added in v0.6.0 

func WithWorkingDirectory(ctx context.Context, dir string) context.Context

WithWorkingDirectory returns a new context with the logical working directory attached.

func WorkingDirectoryFromContext added in v0.6.0 

func WorkingDirectoryFromContext(ctx context.Context) (string, bool)

WorkingDirectoryFromContext retrieves the logical working directory from the context.

Types

type Capability 

type Capability = sdkprovider.Capability

Capability represents the types of operations a provider can perform.

func ExecutionModeFromContext 

func ExecutionModeFromContext(ctx context.Context) (Capability, bool)

ExecutionModeFromContext retrieves the execution mode from the context.

type Contact 

type Contact = sdkprovider.Contact

Contact represents maintainer contact information.

type Descriptor 

type Descriptor = sdkprovider.Descriptor

Descriptor contains provider identity, versioning, schemas, capabilities, and catalog metadata.

type Example 

type Example = sdkprovider.Example

Example represents a usage example for a provider.

type ExecutionMetrics 

type ExecutionMetrics struct {
	ExecutionCount  uint64 `json:"executionCount" yaml:"executionCount" doc:"Total number of executions"`
	SuccessCount    uint64 `json:"successCount" yaml:"successCount" doc:"Number of successful executions"`
	FailureCount    uint64 `json:"failureCount" yaml:"failureCount" doc:"Number of failed executions"`
	TotalDurationNs uint64 `json:"totalDurationNs" yaml:"totalDurationNs" doc:"Total execution duration in nanoseconds"`
	LastExecutionNs uint64 `json:"lastExecutionNs" yaml:"lastExecutionNs" doc:"Timestamp of last execution in nanoseconds since epoch"`
}

ExecutionMetrics tracks execution statistics for a provider.

func (*ExecutionMetrics) AverageDuration 

func (m *ExecutionMetrics) AverageDuration() time.Duration

AverageDuration returns the average execution duration.

func (*ExecutionMetrics) SuccessRate 

func (m *ExecutionMetrics) SuccessRate() float64

SuccessRate returns the success rate as a percentage (0-100).

type ExecutionResult 

type ExecutionResult struct {
	// Provider is the provider that was executed
	Provider Provider `json:"provider" yaml:"provider" doc:"The provider that was executed"`

	// Output is the validated output from the provider
	Output Output `json:"output" yaml:"output" doc:"The validated output from the provider"`

	// DryRun indicates whether this was a dry-run execution
	DryRun bool `json:"dryRun" yaml:"dryRun" doc:"Whether this was a dry-run execution"`

	// ExecutionDuration is the total time taken to execute the provider
	ExecutionDuration time.Duration `json:"executionDuration" yaml:"executionDuration" doc:"The total time taken to execute the provider" example:"1000000000"`

	// ResolvedInputs are the inputs after resolution (for debugging)
	ResolvedInputs map[string]any `json:"resolvedInputs,omitempty" yaml:"resolvedInputs,omitempty" doc:"The resolved inputs (for debugging)"`
}

ExecutionResult contains the result of a provider execution.

func Execute 

func Execute(ctx context.Context, provider Provider, inputs map[string]any) (*ExecutionResult, error)

Execute executes a provider using the global executor.

func ExecuteByName 

func ExecuteByName(ctx context.Context, providerName string, inputs map[string]any) (*ExecutionResult, error)

ExecuteByName executes a provider by name using the global executor.

type Executor 

type Executor struct {
	// contains filtered or unexported fields
}

Executor orchestrates provider execution with input resolution and validation.

func GetGlobalExecutor 

func GetGlobalExecutor() *Executor

GetGlobalExecutor returns the global executor instance.

func NewExecutor 

func NewExecutor(opts ...ExecutorOption) *Executor

NewExecutor creates a new provider executor with the given options.

func (*Executor) Execute 

func (e *Executor) Execute(ctx context.Context, provider Provider, inputs map[string]any) (*ExecutionResult, error)

Execute executes a provider with the given inputs and context. It performs: 1. Execution mode validation against provider capabilities 2. Input resolution (literal, resolver bindings, CEL, templates) 3. Input validation against provider schema 4. Optional decode (if Descriptor.Decode is set) 5. Provider execution (provider checks context for dry-run mode) 6. Output validation against output schema

The context should contain: - Execution mode (via WithExecutionMode) - REQUIRED - Dry-run flag (via WithDryRun) - providers check this to modify behavior - Resolver context (via WithResolverContext) for input resolution

Note: Providers are responsible for handling dry-run mode by checking DryRunFromContext(ctx) and returning appropriate outputs without performing side effects.

func (*Executor) ExecuteByName 

func (e *Executor) ExecuteByName(ctx context.Context, providerName string, inputs map[string]any) (*ExecutionResult, error)

ExecuteByName executes a provider by name from the global registry. This is a convenience method that looks up the provider and calls Execute.

type ExecutorOption 

type ExecutorOption func(*Executor)

ExecutorOption is a functional option for configuring an Executor.

func WithSchemaValidator 

func WithSchemaValidator(validator *SchemaValidator) ExecutorOption

WithSchemaValidator sets a custom schema validator.

type IOStreams added in v0.4.0 

type IOStreams = sdkprovider.IOStreams

IOStreams holds terminal IO writers for providers that support streaming output.

func IOStreamsFromContext added in v0.4.0 

func IOStreamsFromContext(ctx context.Context) (*IOStreams, bool)

IOStreamsFromContext retrieves the IO streams from the context.

type InputResolver 

type InputResolver struct {
	// contains filtered or unexported fields
}

InputResolver resolves provider inputs from various forms into concrete values.

func NewInputResolver 

func NewInputResolver(ctx context.Context, schema *jsonschema.Schema, sensitiveFields []string) *InputResolver

NewInputResolver creates a new input resolver for the given schema and context. The sensitiveFields parameter lists field names that should be redacted in errors.

func (*InputResolver) ResolveInputs 

func (r *InputResolver) ResolveInputs(rawInputs any) (map[string]any, error)

ResolveInputs resolves all provider inputs from their declared forms into concrete values. It validates exclusivity (only one form per property), resolves each input based on its form, applies type coercion, and validates the final values against the schema.

rawInputs is expected to be map[string]InputValue or map[string]any (for backwards compatibility). Returns a map[string]any with resolved concrete values, ready for provider execution.

type InputValue 

type InputValue struct {
	Literal any                        `json:"literal,omitempty" yaml:"literal,omitempty" doc:"Direct static value"`
	Rslvr   string                     `json:"rslvr,omitempty" yaml:"rslvr,omitempty" doc:"Resolver binding (e.g., 'environment')"`
	Expr    celexp.Expression          `json:"expr,omitempty" yaml:"expr,omitempty" doc:"CEL expression to evaluate"`
	Tmpl    gotmpl.GoTemplatingContent `json:"tmpl,omitempty" yaml:"tmpl,omitempty" doc:"Go template to render"`
}

InputValue represents a single input value with exactly one form specified. Only one of Literal, Rslvr, Expr, or Tmpl should be set.

type IterationContext 

type IterationContext = sdkprovider.IterationContext

IterationContext holds information about the current forEach iteration.

func IterationContextFromContext 

func IterationContextFromContext(ctx context.Context) (*IterationContext, bool)

IterationContextFromContext retrieves the iteration context from the context. 

type Link = sdkprovider.Link

Link represents a named hyperlink.

type Metrics 

type Metrics struct {
	// contains filtered or unexported fields
}

Metrics provides global provider metrics collection. It is safe for concurrent use.

func (*Metrics) Disable 

func (m *Metrics) Disable()

Disable turns off metrics collection.

func (*Metrics) Enable 

func (m *Metrics) Enable()

Enable turns on metrics collection.

func (*Metrics) GetAllMetrics 

func (m *Metrics) GetAllMetrics() map[string]*ExecutionMetrics

GetAllMetrics returns a map of all provider metrics. The returned map is a copy and safe to modify.

func (*Metrics) GetMetrics 

func (m *Metrics) GetMetrics(providerName string) *ExecutionMetrics

GetMetrics returns metrics for a specific provider. Returns nil if no metrics have been recorded for the provider.

func (*Metrics) IsEnabled 

func (m *Metrics) IsEnabled() bool

IsEnabled returns whether metrics collection is enabled.

func (*Metrics) Record 

func (m *Metrics) Record(ctx context.Context, providerName string, duration time.Duration, success bool)

Record records an execution result for a provider. When metrics collection is enabled, results are written to both the in-memory store and the global OTel MeterProvider.

func (*Metrics) Reset 

func (m *Metrics) Reset()

Reset clears all collected metrics.

type Output 

type Output = sdkprovider.Output

Output is the standardized return structure for all provider executions.

type Provider 

type Provider = sdkprovider.Provider

Provider is the core interface that all providers must implement.

func Get 

func Get(name string) (Provider, bool)

Get retrieves a provider from the global registry.

func ListByCapability 

func ListByCapability(capability Capability) []Provider

ListByCapability returns providers with the given capability from the global registry.

func ListByCategory 

func ListByCategory(category string) []Provider

ListByCategory returns providers in the given category from the global registry.

func ListProviders 

func ListProviders() []Provider

ListProviders returns all providers from the global registry.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages provider registration and discovery. It ensures global name uniqueness and maintains the latest stable version of each provider.

func GetGlobalRegistry 

func GetGlobalRegistry() *Registry

GetGlobalRegistry returns the global registry instance. This is useful for testing or when you need direct access to the registry.

func NewRegistry 

func NewRegistry(opts ...RegistryOption) *Registry

NewRegistry creates a new provider registry with the given options.

func (*Registry) Clear 

func (r *Registry) Clear()

Clear removes all providers from the registry. This is primarily for testing purposes.

func (*Registry) Count 

func (r *Registry) Count() int

Count returns the number of registered providers.

func (*Registry) DescriptorLookup 

func (r *Registry) DescriptorLookup() func(name string) *Descriptor

DescriptorLookup returns a function that looks up provider descriptors by name. This is used for dependency extraction during resolver phase building. The returned function returns nil if the provider is not found.

func (*Registry) Get 

func (r *Registry) Get(name string) (Provider, bool)

Get retrieves a provider by name. Returns the provider and true if found, nil and false otherwise.

func (*Registry) Has 

func (r *Registry) Has(name string) bool

Has checks if a provider with the given name is registered.

func (*Registry) List 

func (r *Registry) List() []string

List returns a list of all registered provider names. The list is sorted alphabetically.

func (*Registry) ListByCapability 

func (r *Registry) ListByCapability(capability Capability) []Provider

ListByCapability returns providers that support the given capability. The list is sorted alphabetically by provider name.

func (*Registry) ListByCategory 

func (r *Registry) ListByCategory(category string) []Provider

ListByCategory returns providers in the given category. The list is sorted alphabetically by provider name.

func (*Registry) ListProviders 

func (r *Registry) ListProviders() []Provider

ListProviders returns a list of all registered providers. The list is sorted alphabetically by provider name.

func (*Registry) Register 

func (r *Registry) Register(p Provider) error

Register registers a provider in the registry. Returns an error if: - Provider is nil - Provider descriptor is invalid - Provider name already exists (unless allowOverwrite is true) - Provider version is older than existing version

func (*Registry) Unregister 

func (r *Registry) Unregister(name string) bool

Unregister removes a provider from the registry. Returns true if the provider was removed, false if it didn't exist. This is primarily for testing purposes.

type RegistryOption 

type RegistryOption func(*registryOptions)

RegistryOption is a functional option for configuring a Registry.

func WithAllowOverwrite 

func WithAllowOverwrite(allow bool) RegistryOption

WithAllowOverwrite allows overwriting existing providers in the registry. This is primarily for testing purposes and should not be used in production.

type SchemaValidator 

type SchemaValidator = sdkprovider.SchemaValidator

SchemaValidator provides validation for provider inputs and outputs against JSON Schema definitions.

func NewSchemaValidator 

func NewSchemaValidator() *SchemaValidator

NewSchemaValidator creates a new schema validator.

type SolutionMeta added in v0.6.0 

type SolutionMeta = sdkprovider.SolutionMeta

SolutionMeta holds solution metadata fields made available to providers via context.

func SolutionMetadataFromContext added in v0.6.0 

func SolutionMetadataFromContext(ctx context.Context) (*SolutionMeta, bool)

SolutionMetadataFromContext retrieves the solution metadata from the context.

type ValidationError 

type ValidationError = sdkprovider.ValidationError

ValidationError represents a single field validation error with contextual information.

type ValidationErrors 

type ValidationErrors = sdkprovider.ValidationErrors

ValidationErrors is a collection of validation errors.

Source Files

View all Source files

Directories

Path Synopsis
celprovider
debugprovider
directoryprovider
envprovider
execprovider
fileprovider
githubprovider
Package githubprovider implements a provider for GitHub API operations.
 Package githubprovider implements a provider for GitHub API operations.
gitprovider
gotmplprovider
hclprovider
httpprovider
identityprovider
Package identityprovider provides authentication identity information from auth handlers.
 Package identityprovider provides authentication identity information from auth handlers.
messageprovider
metadataprovider
parameterprovider
secretprovider
Package secretprovider implements a resolver provider for accessing encrypted secrets.
 Package secretprovider implements a resolver provider for accessing encrypted secrets.
sleepprovider
solutionprovider
staticprovider
validationprovider
Package detail provides shared business logic for building structured provider information.
 Package detail provides shared business logic for building structured provider information.
Package schemahelper provides ergonomic builder functions for constructing jsonschema.Schema objects used in provider descriptors.
 Package schemahelper provides ergonomic builder functions for constructing jsonschema.Schema objects used in provider descriptors.

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.