Documentation
¶
Index ¶
- Constants
- func DefaultVersion() *semver.Version
- func NextPatchVersion(ctx context.Context, cat catalog.Catalog, kind catalog.ArtifactKind, ...) (*semver.Version, error)
- func ResolveArtifactName(explicitName, metadataName, filePath string) (string, error)
- func ResolveArtifactVersion(explicitVersion string, metadataVersion *semver.Version) (*semver.Version, bool, error)
- type Bundle
- type Catalog
- type Contact
- type Link
- type Metadata
- type PluginDependency
- type PluginKind
- type Solution
- func (s *Solution) ApplyDefaults()
- func (s *Solution) FromJSON(data []byte) error
- func (s *Solution) FromYAML(data []byte) error
- func (s *Solution) GetPath() string
- func (s *Solution) LoadFromBytes(bytes []byte) error
- func (s *Solution) RawContent() []byte
- func (s *Solution) SetPath(path string)
- func (s *Solution) SetSourceMap(sm *sourcepos.SourceMap)
- func (s *Solution) SourceMap() *sourcepos.SourceMap
- func (s *Solution) ToJSON() ([]byte, error)
- func (s *Solution) ToJSONPretty() ([]byte, error)
- func (s *Solution) ToYAML() ([]byte, error)
- func (s *Solution) UnmarshalFromBytes(bytes []byte) error
- func (s *Solution) Validate() error
- func (s *Solution) ValidateSpec() error
- type Spec
Constants ¶
const ( // DefaultAPIVersion is the default API version for Solution resources DefaultAPIVersion = "scafctl.io/v1" // SolutionKind is the Kind identifier for Solution resources SolutionKind = "Solution" )
Variables ¶
This section is empty.
Functions ¶
func DefaultVersion ¶ added in v0.8.0
DefaultVersion returns a copy of the default placeholder version.
func NextPatchVersion ¶ added in v0.10.0
func NextPatchVersion(ctx context.Context, cat catalog.Catalog, kind catalog.ArtifactKind, name string) (*semver.Version, error)
NextPatchVersion queries the catalog for existing versions of the named artifact and returns the next patch version. If no versions exist, it returns 0.1.0.
func ResolveArtifactName ¶ added in v0.6.0
ResolveArtifactName determines the artifact name using the following priority:
- explicitName (e.g., --name flag)
- metadataName (from solution metadata.name)
- derived from filePath (e.g., "my-solution.yaml" → "my-solution")
Returns an error if the resolved name is empty or fails catalog.IsValidName validation.
func ResolveArtifactVersion ¶ added in v0.6.0
func ResolveArtifactVersion(explicitVersion string, metadataVersion *semver.Version) (*semver.Version, bool, error)
ResolveArtifactVersion determines the artifact version using the following priority:
- explicitVersion (e.g., --version flag)
- metadataVersion (from solution metadata.version)
Returns the resolved version, whether an explicit version overrides a different metadata version (callers may want to log a warning), and any error.
Types ¶
type Bundle ¶
type Bundle struct {
// Include is a list of glob patterns or explicit file paths to bundle.
// Paths are relative to the directory containing the solution YAML file.
Include []string `json:"include,omitempty" yaml:"include,omitempty" doc:"Glob patterns or file paths to include in the bundle" maxItems:"1000"`
// Plugins declares external plugins required by this solution.
Plugins []PluginDependency `json:"plugins,omitempty" yaml:"plugins,omitempty" doc:"External plugins required by this solution" maxItems:"50"`
}
Bundle defines files and plugins to include when building a solution into a catalog artifact. This section is build-time metadata only and does not affect execution.
type Catalog ¶
type Catalog struct {
// Visibility controls who can discover and use the solution.
// Valid values: "public", "private", "internal"
Visibility string `` /* 179-byte string literal not displayed */
// Beta indicates if the solution is in beta/preview status
Beta bool `json:"beta,omitempty" yaml:"beta,omitempty" doc:"Indicates if the solution is in beta" required:"false"`
// Disabled marks the solution as unavailable (but keeps it in the catalog)
Disabled bool `json:"disabled,omitempty" yaml:"disabled,omitempty" doc:"Indicates if the solution is disabled" required:"false"`
}
Catalog controls distribution and visibility of the solution. Catalog metadata does not affect execution behavior.
type Contact ¶
type Contact struct {
Name string `` /* 153-byte string literal not displayed */
Email string `` /* 199-byte string literal not displayed */
}
Contact represents the maintainer's contact information, including their name and email address. The Name field must be between 3 and 60 characters and can include letters, spaces, and certain punctuation. The Email field must be a valid email address between 5 and 100 characters.
type Link ¶
type Link struct {
Name string `` /* 154-byte string literal not displayed */
URL string `` /* 173-byte string literal not displayed */
}
Link represents a named hyperlink with validation constraints on its fields. Name must be 3-30 characters and match the allowed pattern. URL must be a valid URI, 12-500 characters, and start with http or https.
type Metadata ¶
type Metadata struct {
// Name is the unique identifier for the solution (e.g., "gcp-basic")
Name string `` /* 152-byte string literal not displayed */
// Version is the semantic version of the solution.
// Optional for local development; required for catalog publishing (build/push).
Version *semver.Version `` /* 318-byte string literal not displayed */
// DisplayName is the human-readable name of the solution
DisplayName string `` /* 188-byte string literal not displayed */
// Description provides details about the solution's purpose
Description string `` /* 246-byte string literal not displayed */
// Category classifies the solution (e.g., "application", "infrastructure")
Category string `` /* 196-byte string literal not displayed */
// Tags are searchable keywords associated with the solution
Tags []string `json:"tags,omitempty" yaml:"tags,omitempty" maxItems:"100" doc:"A list of tags for the solution" required:"false"`
// Maintainers lists the people or teams responsible for the solution
Maintainers []Contact `` /* 139-byte string literal not displayed */
// Links provides references to related documentation or resources
Links []Link `json:"links,omitempty" yaml:"links,omitempty" doc:"Links to content related to the solution" maxItems:"10" required:"false"`
// Icon is a URL or path to an icon image for the solution
Icon string `` /* 196-byte string literal not displayed */
// Banner is a URL or path to a banner image for the solution
Banner string `` /* 202-byte string literal not displayed */
}
Metadata contains the descriptive information about a solution. Metadata is immutable per version and does not affect execution.
type PluginDependency ¶
type PluginDependency struct {
// Name is the plugin's catalog reference (e.g., "aws-provider").
Name string `` /* 192-byte string literal not displayed */
// Kind is the plugin type.
Kind PluginKind `json:"kind" yaml:"kind" doc:"Plugin type" example:"provider"`
// Version is a semver constraint (e.g., "^1.5.0", ">=2.0.0", "3.1.2").
Version string `` /* 157-byte string literal not displayed */
// Defaults provides default values for plugin inputs.
// These are shallow-merged beneath inline provider inputs (inline always wins).
Defaults map[string]*spec.ValueRef `json:"defaults,omitempty" yaml:"defaults,omitempty" doc:"Default input values for this plugin (supports ValueRef)"`
}
PluginDependency declares an external plugin required by a solution.
type PluginKind ¶
type PluginKind string
PluginKind is the type of plugin (provider, auth-handler).
const ( // PluginKindProvider represents a provider plugin. PluginKindProvider PluginKind = "provider" // PluginKindAuthHandler represents an auth handler plugin. PluginKindAuthHandler PluginKind = "auth-handler" )
func (PluginKind) IsValid ¶
func (k PluginKind) IsValid() bool
IsValid returns true if the plugin kind is a recognized value.
type Solution ¶
type Solution struct {
// APIVersion defines the versioned schema of this representation of a Solution.
// Default: "scafctl.io/v1"
APIVersion string `` /* 157-byte string literal not displayed */
// Kind is a string value representing the REST resource this object represents.
// Must be "Solution".
Kind string `json:"kind" yaml:"kind" doc:"The kind of resource" example:"Solution" pattern:"^Solution$"`
// Metadata describes the solution as a product. It is immutable per version
// and is indexed in the catalog. Metadata does not affect execution.
Metadata Metadata `json:"metadata" yaml:"metadata" doc:"Metadata about the solution"`
// Catalog controls distribution and visibility, not execution.
// Published artifacts are JSON-only, and solutions are version-addressable (e.g., gcp-basic@1.0.1).
Catalog Catalog `json:"catalog,omitempty" yaml:"catalog,omitempty" doc:"Catalog metadata for distribution" required:"false"`
// Compose lists relative paths to partial YAML files merged into this solution at build/load time.
// Each path must be relative to the directory containing this solution YAML file.
Compose []string `` /* 133-byte string literal not displayed */
// Bundle defines files and plugins to include when building a solution into a catalog artifact.
// This section is build-time metadata only and does not affect execution.
Bundle Bundle `json:"bundle,omitempty" yaml:"bundle,omitempty" doc:"Build-time bundling configuration"`
// Spec defines the execution specification containing resolvers, templates, and actions.
// This is where the actual work of the solution is defined.
Spec Spec `json:"spec,omitempty" yaml:"spec,omitempty" doc:"Execution specification"`
// contains filtered or unexported fields
}
Solution represents a Kubernetes-style declarative unit of behavior in scafctl. It follows the apiVersion/kind pattern and separates concerns into metadata, spec, and catalog sections.
A solution combines:
- resolvers (data resolution)
- templates (data to files or artifacts)
- actions (explicit side effects)
The solution is a data model that scafctl executes deterministically, not a script or pipeline.
Example:
apiVersion: scafctl.io/v1 kind: Solution metadata: name: gcp-basic version: 1.0.1 displayName: Basic GCP Solution catalog: visibility: public beta: false
func (*Solution) ApplyDefaults ¶
func (s *Solution) ApplyDefaults()
ApplyDefaults populates default values for optional top-level fields. It is safe to call on a nil receiver.
func (*Solution) FromJSON ¶
FromJSON unmarshals the provided JSON data into the Solution struct. It returns an error if the unmarshalling fails.
func (*Solution) FromYAML ¶
FromYAML unmarshals the provided YAML data into the Solution struct. It also builds a SourceMap that maps logical YAML paths to source positions. It returns an error if the unmarshalling process fails.
func (*Solution) LoadFromBytes ¶
LoadFromBytes unmarshals the provided bytes, applies defaults, and validates the solution. It is a convenience helper to ensure envelope normalization happens consistently.
func (*Solution) RawContent ¶ added in v0.8.0
RawContent returns a copy of the original bytes used to parse this solution. It preserves the original formatting for round-trip fidelity. Returns nil if the solution was not loaded from bytes.
func (*Solution) SetPath ¶
SetPath sets the path for the Solution. It updates the internal path field with the provided value.
func (*Solution) SetSourceMap ¶ added in v0.5.0
SetSourceMap sets the source map for this solution. This is useful when composing solutions from multiple files.
func (*Solution) SourceMap ¶ added in v0.5.0
SourceMap returns the source map for this solution, if available. The source map is populated during FromYAML and maps logical YAML paths (e.g., "spec.resolvers.appName") to source positions (line, column, file). Returns nil if the solution was not loaded from YAML or if source map building failed.
func (*Solution) ToJSON ¶
ToJSON serializes the Solution struct into JSON format. It returns the resulting JSON as a byte slice and any error encountered during marshaling.
func (*Solution) ToJSONPretty ¶
ToJSONPretty serializes the Solution struct into a pretty-printed JSON format. It returns the resulting JSON as a byte slice and any error encountered during marshaling.
func (*Solution) ToYAML ¶
ToYAML serializes the Solution struct into YAML format. It returns the resulting YAML as a byte slice, or an error if serialization fails.
func (*Solution) UnmarshalFromBytes ¶
UnmarshalFromBytes attempts to unmarshal the provided byte slice into the Solution struct. It first tries to unmarshal using YAML format. If that fails and the content looks like JSON, it attempts to unmarshal using JSON format. Returns only the relevant error for clarity.
func (*Solution) Validate ¶
Validate performs lightweight runtime validation on the Solution envelope. It enforces apiVersion/kind, required metadata, and catalog enums.
func (*Solution) ValidateSpec ¶
ValidateSpec performs validation specific to the spec section of a solution. It validates resolver naming conventions and checks for circular dependencies.
type Spec ¶
type Spec struct {
// Resolvers is a map of resolver definitions keyed by their name.
// Resolver names must be unique and cannot start with "__" (reserved for internal use).
Resolvers map[string]*resolver.Resolver `json:"resolvers,omitempty" yaml:"resolvers,omitempty" doc:"Resolver definitions keyed by name"`
// Workflow defines the action execution specification.
// Actions consume resolved data from resolvers and perform side-effect operations.
// All resolvers are evaluated before any action execution begins.
Workflow *action.Workflow `json:"workflow,omitempty" yaml:"workflow,omitempty" doc:"Action workflow specification"`
// Testing groups all test-related configuration (test cases and config) under one property.
Testing *soltesting.TestSuite `json:"testing,omitempty" yaml:"testing,omitempty" doc:"Test suite configuration"`
}
Spec defines the execution specification for a solution. It contains resolvers that perform data resolution, transformation, and validation, and optionally a workflow that defines actions to execute.
func (*Spec) HasActions ¶
HasActions returns true if the workflow contains any actions (regular or finally).
func (*Spec) HasResolvers ¶
HasResolvers returns true if the spec contains any resolver definitions.
func (*Spec) HasTestConfig ¶ added in v0.3.0
HasTestConfig returns true if the spec has test configuration.
func (*Spec) HasTesting ¶ added in v0.5.0
HasTesting returns true if the spec has a testing suite defined.
func (*Spec) HasTests ¶ added in v0.3.0
HasTests returns true if the spec contains any test definitions.
func (*Spec) HasWorkflow ¶
HasWorkflow returns true if the spec contains a workflow definition.
func (*Spec) ResolversToSlice ¶
ResolversToSlice converts the Resolvers map to a slice for execution. It ensures each resolver's Name field is set to match its map key.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package builder provides the build pipeline for composing, discovering, vendoring, and bundling solution artifacts.
|
Package builder provides the build pipeline for composing, discovering, vendoring, and bundling solution artifacts. |
|
Package execute provides business logic for validating and executing solutions.
|
Package execute provides business logic for validating and executing solutions. |
|
Package inspect provides business logic for inspecting and explaining solutions.
|
Package inspect provides business logic for inspecting and explaining solutions. |
|
Package prepare provides a standalone function for loading and preparing a solution for execution.
|
Package prepare provides a standalone function for loading and preparing a solution for execution. |
|
Package render provides domain logic for rendering solutions, including resolver execution, registry adapters, and configuration merging.
|
Package render provides domain logic for rendering solutions, including resolver execution, registry adapters, and configuration merging. |
|
Package soltesting provides types and utilities for functional testing of solutions.
|
Package soltesting provides types and utilities for functional testing of solutions. |
|
mockexec
Package mockexec provides a configurable mock for shell command execution in functional tests.
|
Package mockexec provides a configurable mock for shell command execution in functional tests. |
|
mockserver
Package mockserver provides a configurable HTTP mock server for functional testing.
|
Package mockserver provides a configurable HTTP mock server for functional testing. |
|
Package walk provides a visitor/walker pattern for traversing solution structures.
|
Package walk provides a visitor/walker pattern for traversing solution structures. |