Documentation
¶
Overview ¶
Package source resolves scaffold templates from local paths or remote sources (git, https, s3, oci) into a templates.Configuration ready for generation. It is the seam that lets `atmos init`/`atmos scaffold` distribute templates remotely while reusing the existing generator engine.
Index ¶
- Constants
- func CheckNotSwitchedFromRendered(targetDir string) error
- func Hydrate(stub *templates.Configuration, override string) (func(), error)
- func IsPinnableSource(src string) bool
- func IsTemplateSource(value string) bool
- func Resolve(atmosConfig *schema.AtmosConfiguration, name, src string, ...) (*templates.Configuration, func(), error)
- func ValidateRenderedSource(src, resolvedRef string) error
- func WithDepth(src string, depth int) (string, error)
- func WithRef(src, ref string) string
- type Directory
- type FetchOption
- type FetchProgress
- type InitSource
- type RenderedBase
Constants ¶
const DefaultFetchTimeout = 5 * time.Minute
DefaultFetchTimeout bounds how long a remote scaffold fetch may take.
const UnpinnedRenderedRefMarker = "unpinned"
UnpinnedRenderedRefMarker is recorded as spec.renderedRef for --update-strategy=rendered generations whose source has no immutable ref to pin at all (see IsPinnableSource: local path, file://, s3::, or a plain http(s) archive). Resolve legitimately leaves Configuration.ResolvedRef empty for those source kinds, but SaveProjectRecord only ever persists a non-empty spec.renderedRef, and ResolveRenderedBase/CheckNotSwitchedFromRendered both key off spec.renderedRef being non-empty to recognize "this project was generated under rendered" -- an empty ResolvedRef there would silently make the record look exactly like one that was never generated under rendered at all, breaking both a later rendered update (which would wrongly fail with "no recorded rendered-strategy history") and a later tracked update (which would wrongly skip CheckNotSwitchedFromRendered's guard and attempt a 3-way merge against stale or absent git history).
Recording it is safe: pinRenderedRef leaves any non-git/non-oci src completely unchanged regardless of the ref passed to it (replaceRef's own !vendor.IsGitURI(src) no-op), so recording this marker for a non-pinnable source never corrupts the source that ResolveRenderedBase re-fetches -- it only exists to keep spec.renderedRef non-empty for those two checks.
Variables ¶
This section is empty.
Functions ¶
func CheckNotSwitchedFromRendered ¶ added in v1.230.0
CheckNotSwitchedFromRendered errors if targetDir's recorded project state shows it was last managed with --update-strategy=rendered (spec.renderedRef set, spec.baseRef empty), so a --update-strategy=tracked run doesn't silently attempt a 3-way merge against a target that was deliberately generated with no git-history dependency -- it would either read stale history from before rendered mode took over, or fail with the generic, less-helpful "requires a git repository" message instead of naming what actually happened.
A missing or never-updated project record is not an error here: only a confirmed rendered-mode history is a real switch worth flagging.
func Hydrate ¶
func Hydrate(stub *templates.Configuration, override string) (func(), error)
Hydrate materializes a catalog/remote stub (a Configuration with no Files but a Source) into a full template by fetching its Source. Full templates (embedded or already-loaded local) are returned unchanged with a no-op cleanup. The returned cleanup must be called after generation completes.
func IsPinnableSource ¶ added in v1.230.0
IsPinnableSource reports whether src is a source kind for which Resolve records an immutable ResolvedRef (a git:: commit SHA or an oci:// manifest digest -- see fetchRemoteSource and fetchOCI's respective captures). Local paths, file://, s3::, and plain http(s) archive sources have no equivalent immutable identity to pin to, so Resolve legitimately leaves ResolvedRef empty for them; this distinguishes that expected, by-design case from an unresolved git/oci ref, which instead signals a resolution failure that callers should not paper over with UnpinnedRenderedRefMarker.
func IsTemplateSource ¶
IsTemplateSource reports whether an init/scaffold template argument looks like a direct source rather than a catalog or embedded template key.
func Resolve ¶
func Resolve(atmosConfig *schema.AtmosConfiguration, name, src string, timeout time.Duration) (*templates.Configuration, func(), error)
Resolve fetches a scaffold template from src (a local path, file://, an oci:// registry reference, or a go-getter remote such as git/https/s3) into a usable templates.Configuration. The returned cleanup function removes any temporary download directory; it is never nil and is always safe to call.
func ValidateRenderedSource ¶ added in v1.230.0
ValidateRenderedSource rejects a --update-strategy=rendered generation up front when src/resolvedRef can never produce a project record a later rendered update can actually reconstruct from -- rather than silently generating now and only failing at that later update, once the answers that produced this generation are no longer easily reproducible.
A record is reconstructible in exactly two cases:
- src is a pinnable source (see IsPinnableSource: git:: or oci://) and resolvedRef is non-empty -- the normal case, an immutable commit SHA or manifest digest recorded as spec.renderedRef.
- src is a non-pinnable source Hydrate can still re-fetch verbatim by src itself (a local path, file://, or s3::/plain http(s) archive) -- UnpinnedRenderedRefMarker documents that case; it is not immutable, but a later Hydrate(src) call still succeeds.
It is NOT reconstructible for:
- config.SourceEmbedded ("embedded"): a template bundled into the Atmos binary has no fetchable location Hydrate can re-resolve by that literal string, so a later rendered update would always fail regardless of what gets recorded now.
- a pinnable source (git/oci) whose ref failed to resolve: recording UnpinnedRenderedRefMarker there would corrupt replaceRef's git ref= query parameter with the literal marker string on the next fetch attempt (see UnpinnedRenderedRefMarker's own doc comment for why the marker is safe only for non-git/non-oci sources), so this is deliberately not treated the same as the local/s3/http case above.
Types ¶
type Directory ¶ added in v1.231.0
Directory is a fetched source whose contents have not been interpreted. Its path remains valid until the FetchDirectory cleanup function is called.
func FetchDirectory ¶ added in v1.231.0
func FetchDirectory(atmosConfig *schema.AtmosConfiguration, name, src string, timeout time.Duration, opts ...FetchOption) (*Directory, func(), error)
FetchDirectory acquires a local or remote directory without requiring a scaffold manifest. The returned cleanup function is always safe to call, including after errors.
func (*Directory) LoadScaffold ¶ added in v1.231.0
func (d *Directory) LoadScaffold(name, src string) (*templates.Configuration, error)
LoadScaffold interprets a fetched directory using the strict scaffold contract.
type FetchOption ¶ added in v1.231.0
type FetchOption func(*fetchOptions)
FetchOption configures directory fetching.
func WithProgress ¶ added in v1.231.0
func WithProgress(progress FetchProgress) FetchOption
WithProgress reuses the caller's progress indicator during remote downloads.
type FetchProgress ¶ added in v1.231.0
type FetchProgress interface {
Update(string)
}
FetchProgress updates an indicator owned by the caller instead of starting a separate download spinner. The caller remains responsible for stopping it.
type InitSource ¶ added in v1.231.0
InitSource identifies a directory and its default initialization behavior.
func NormalizeInitSource ¶ added in v1.231.0
func NormalizeInitSource(value, ref string) (InitSource, error)
NormalizeInitSource expands official example aliases and GitHub directory URLs. GitHub browser URLs use one path segment for the revision; refs containing slashes should use the canonical //directory syntax and --ref instead.
type RenderedBase ¶ added in v1.230.0
type RenderedBase struct {
// Config is the old ref's fully-hydrated template configuration.
Config *templates.Configuration
// Values is that generation's own recorded answers.
Values map[string]interface{}
// Cleanup releases the temporary fetch directory Config's Files were
// hydrated into. Always non-nil on success; must be called once the
// merge that consumes Config is done.
Cleanup func()
}
RenderedBase bundles ResolveRenderedBase's results (grouped into a struct, rather than four separate return values, to stay under revive's function-result-limit).
func ResolveRenderedBase ¶ added in v1.230.0
func ResolveRenderedBase(targetDir, sourceOverride string) (*RenderedBase, error)
ResolveRenderedBase loads targetDir's own recorded project state (.atmos/scaffold.yaml, written by the last successful generation) and fetches the template pinned at the resolved ref recorded there (spec.renderedRef -- a commit SHA for git sources, a manifest digest for OCI sources, see pinRenderedRef), so engine.UpdateStrategyRendered can re-render it as the 3-way merge base.
Must be called before this run's own SaveProjectRecord overwrites that file -- the whole point is to capture "what generated what's currently on disk" before this run's new answers replace it.
Returns ErrRenderedStrategyRequiresConfig if no project record exists, or one exists but was never generated under rendered at all (neither spec.renderedRef nor spec.baseRef is set). Unlike UpdateStrategyTracked (which falls back to literal "HEAD" against the target's own git history when no metadata is pinned), there is no equivalent fallback here -- a pristine re-render needs a real commit and real answers to reconstruct, not an assumption.
Returns ErrUpdateStrategySwitchedToRendered if the record shows spec.baseRef set and spec.renderedRef empty: the project was last managed with tracked, which never records a resolved commit SHA for the template source, so there is nothing here to re-render from.
Source Files