Documentation
¶
Overview ¶
Package deferred selects, evaluates, and caches only the values a caller needs. Authentication resolution belongs to pkg/auth/deferred.
Index ¶
- func CanRecover(err error, enabled bool, existing func(error) bool) bool
- func ExcludeComputedFields(dctx *m.DeferredMergeContext, section map[string]any)
- func ExpandEvaluationPaths(data map[string]any, paths [][]string, delimiters ...string) [][]string
- func FilterDeferredFields(dctx *m.DeferredMergeContext, section string, paths [][]string)
- func IsCacheable(value any) bool
- func IsSectionRequired(sections []string, sectionName string) bool
- func PathsForQuery(query string) [][]string
- func RenderValues(input map[string]any, evaluate func(string) (any, error)) (map[string]any, error)
- func RestoreEvaluationFields(result, excluded map[string]any)
- func SplitEvaluationFields(data map[string]any, paths [][]string) (map[string]any, map[string]any)
- func SplitSectionsByRequirement(componentSection map[string]any, sections []string) (filtered, excluded map[string]any)
- func StarlarkReferences(value string) ([][]string, bool)
- type Func
- type Resolver
- type ValueCache
- type ValueProcessor
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CanRecover ¶
CanRecover adds credential unavailability to a caller's existing value policy. Providers classify their errors; this package does not interpret SDK error codes.
func ExcludeComputedFields ¶
func ExcludeComputedFields(dctx *m.DeferredMergeContext, section map[string]any)
ExcludeComputedFields prevents a second substitution during deferred merging.
func ExpandEvaluationPaths ¶
ExpandEvaluationPaths includes fields referenced by selected template values. Dynamic scope/root access cannot be proven safe to narrow, so it evaluates fully. Optional delimiters keep dependency analysis aligned with template rendering.
func FilterDeferredFields ¶
func FilterDeferredFields(dctx *m.DeferredMergeContext, section string, paths [][]string)
FilterDeferredFields applies the same demand boundary to the final merge pass. An ancestor function must run when it can supply a requested descendant.
func IsCacheable ¶
IsCacheable reports whether a successful lookup contains a reusable value. Computed placeholders and nil results must remain retryable.
func IsSectionRequired ¶
IsSectionRequired reports whether sectionName must be evaluated (rendered as a Go template and/or have its YAML functions resolved) given an eval-sections filter.
A nil filter disables gating entirely: every section is required, matching the historical eager-evaluation behavior exactly. This is what every existing caller gets (describe stacks, terraform, helmfile, hooks, etc.) since only the `list stacks`/`list components`/ `list instances` commands ever construct a non-nil filter (see column.RequiredSections). A non-nil filter (even an empty one, meaning "no column needs any section") gates by membership.
Deliberately checks `sections == nil`, NOT `len(sections) == 0`: an empty-but-non-nil slice is a real, valid "nothing is required" filter and must NOT be treated the same as "no filter" -- collapsing the two (as a bare len() check would) would silently disable gating exactly when it matters most (default `list stacks` columns, which reference no section at all). Do not "simplify" this to `len(sections) == 0` -- that reintroduces the spurious eager-evaluation bug this file exists to fix.
func PathsForQuery ¶
PathsForQuery narrows simple field queries. Arbitrary YQ expressions conservatively evaluate the entire value, including all filter dependencies.
func RenderValues ¶
RenderValues evaluates each scalar separately, preserving successful siblings.
func RestoreEvaluationFields ¶
func SplitEvaluationFields ¶
func SplitSectionsByRequirement ¶
func SplitSectionsByRequirement(componentSection map[string]any, sections []string) (filtered, excluded map[string]any)
SplitSectionsByRequirement returns a shallow copy of componentSection restricted to the top-level sections IsSectionRequired approves, plus the sections that were left out so the caller can restore them untouched afterward (see restoreNonTemplatedSections, reused here generically since "copy excluded keys back in" is identical for both use cases).
A nil filter (gating disabled) returns the input unchanged with a nil excluded map -- the same "nothing was split" shape splitNonTemplatedSections uses for its own no-op case, so both exclusion sources can be restored through the same helper without special-casing nil.
func StarlarkReferences ¶
StarlarkReferences returns the configuration fields a !starlark value reads through ctx, so a selective command can evaluate only those fields instead of the whole component. Recognized reads are ctx.<section>.<name> and ctx.<section>["name"] (chains of either form, and ctx.<section>.get("name")), where the section is vars, metadata, settings, env, or locals, and the identity fields ctx.stack, ctx.component, and ctx.component_type.
It reports false when the value reads configuration in a way static analysis cannot bound: a whole section (dict(ctx.vars), json.encode(ctx.vars), iteration, an alias such as v = ctx.vars), a computed key (ctx.vars[name]), items(), keys(), values(), a get() whose key is not a string literal, ctx itself used as a value, an unknown ctx field, or source that does not parse. The caller then evaluates the full component, as it does for any construct it cannot analyze.
Types ¶
type Resolver ¶
Resolver supplies a value only when requested. Implementations own their dependencies and failure semantics; callers own display and recovery policy.
type ValueCache ¶
type ValueCache struct {
// contains filtered or unexported fields
}
ValueCache holds successfully resolved values for one target and effective configuration. Its owner determines the lifetime and supplies the configuration-specific key.
func (*ValueCache) Load ¶
func (c *ValueCache) Load(kind string) (any, bool)
Load retrieves a resolved value; a nil cache means caching is disabled.
func (*ValueCache) LoadOrStore ¶
func (c *ValueCache) LoadOrStore(kind string, value any) any
LoadOrStore binds a stable value to this target's effective configuration. A nil cache or an unresolved value remains uncached.
func (*ValueCache) Store ¶
func (c *ValueCache) Store(kind string, value any)
Store rejects unresolved computed values. Callers must partition inspection placeholders from execution values using separate kinds.
type ValueProcessor ¶
type ValueProcessor struct {
Inner m.YAMLFunctionProcessor
Recoverable func(error) bool
Warn func(string, error)
}
ValueProcessor applies recovery at an individual YAML value boundary.
func (*ValueProcessor) ProcessYAMLFunctionString ¶
func (p *ValueProcessor) ProcessYAMLFunctionString(value string) (any, error)
Source Files