Documentation
¶
Overview ¶
Package imports provides functionality for processing stack imports, including support for remote imports from URLs via go-getter.
Index ¶
- func DecodeObject(raw any) (schema.StackImport, error)
- func DownloadRemoteImport(atmosConfig *schema.AtmosConfiguration, uri string) (string, error)
- func HasSchemeSeparator(uri string) bool
- func IsActive(imp *schema.StackImport, ctx *condition.Context) bool
- func IsGCSURI(uri string) bool
- func IsGitURI(uri string) bool
- func IsHTTPURI(uri string) bool
- func IsLocalPath(uri string) bool
- func IsOCIURI(uri string) bool
- func IsRemote(uri string) bool
- func IsS3URI(uri string) bool
- func IsTemplateFile(filePath string) bool
- func IsTemplatedPath(importPath string) bool
- func MergeLabels(layers ...schema.StackImportLabels) schema.StackImportLabels
- func ProcessImportPath(atmosConfig *schema.AtmosConfiguration, basePath, importPath string) (string, error)
- func ReadMetadata(content string, delimiters []string) schema.StackImportMetadata
- func ResolveImportPaths(atmosConfig *schema.AtmosConfiguration, basePath string, importPaths []string) ([]string, error)
- func ResolveLocal(importPath, importingFile, stacksBasePath string) ([]string, error)
- func ValidateStaticImportPath(atmosConfig *schema.AtmosConfiguration, path, manifest string) error
- func WhenContext() condition.Context
- type MetadataScope
- func (scope MetadataScope) Activate(ctx *condition.Context, imported, local schema.StackImportMetadata) error
- func (scope MetadataScope) Child(imported, local schema.StackImportMetadata) (MetadataScope, error)
- func (scope MetadataScope) Merge(layers ...schema.StackImportMetadata) (schema.StackImportMetadata, error)
- type RemoteImportMatch
- type RemoteImporter
- type RemoteImporterOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeObject ¶
func DecodeObject(raw any) (schema.StackImport, error)
DecodeObject decodes one object-form entry of a stack manifest's `import` section, including its optional `when` condition (a predicate, a list, a map, or a `!cel` expression).
func DownloadRemoteImport ¶
func DownloadRemoteImport(atmosConfig *schema.AtmosConfiguration, uri string) (string, error)
DownloadRemoteImport is a convenience function that uses the global importer.
func HasSchemeSeparator ¶
HasSchemeSeparator checks if the URI contains a scheme separator. Examples:
- true: "https://github.com", "git::https://...", "s3::https://...".
- false: "github.com/repo", "./local/path", "components/terraform".
func IsActive ¶
func IsActive(imp *schema.StackImport, ctx *condition.Context) bool
IsActive reports whether the import should be processed. An import without a `when` condition is always active. A condition that cannot be evaluated does not match, the same as for the `import:` list in `atmos.yaml`. The usual cause is a CEL expression that reads an unset environment variable, such as `env.DEPLOY_ENV == "prod"`, and that should skip the import rather than fail. The reason is logged at debug level.
func IsGitURI ¶
IsGitURI checks if the URI appears to be a Git repository URL. Detection rules: 1. Explicit git:: prefix. 2. SCP-style URLs (git@github.com:owner/repo.git). 3. Known Git hosting platforms (github.com, gitlab.com, bitbucket.org) in host. 4. .git extension in path (not in host). 5. Azure DevOps _git/ pattern in path.
func IsLocalPath ¶
IsLocalPath checks if the URI is a local file system path. Examples:
- Local: "/absolute/path", "./relative/path", "../parent/path", "components/terraform".
- Remote: "github.com/owner/repo", "https://example.com", "git.company.com/repo".
func IsOCIURI ¶
IsOCIURI checks if the URI references an OCI registry artifact (oci://host/repo:tag). It must be checked before IsGitURI, which can match hosts such as github.com inside an oci:// URI.
func IsRemote ¶
IsRemote returns true if the URI is a remote URL that should be downloaded. This is the inverse of IsLocalPath.
func IsS3URI ¶
IsS3URI checks if the URI is an S3 URI. Go-getter supports both explicit s3:: prefix and auto-detected .amazonaws.com URLs.
func IsTemplateFile ¶
IsTemplateFile reports whether a resolved import file is a Go template file (`.yaml.tmpl` or `.yml.tmpl`) that must be rendered before it can be parsed as YAML.
func IsTemplatedPath ¶
IsTemplatedPath reports whether an import path contains a Go template expression. Templated import paths can only be resolved at stack-processing time (they depend on the `settings`/`vars`/`env` sections of earlier imports), so static resolvers skip them.
func MergeLabels ¶
func MergeLabels(layers ...schema.StackImportLabels) schema.StackImportLabels
MergeLabels merges label layers in increasing precedence without mutating any input.
func ProcessImportPath ¶
func ProcessImportPath(atmosConfig *schema.AtmosConfiguration, basePath, importPath string) (string, error)
ProcessImportPath resolves an import path (local or remote) to a local file path. For local paths, it joins with basePath. For remote URLs, it downloads and returns the temp file path.
func ReadMetadata ¶
func ReadMetadata(content string, delimiters []string) schema.StackImportMetadata
ReadMetadata extracts literal stack-wide labels and tags without running templates or functions.
func ResolveImportPaths ¶
func ResolveImportPaths(atmosConfig *schema.AtmosConfiguration, basePath string, importPaths []string) ([]string, error)
ResolveImportPaths resolves multiple import paths, returning local file paths. This is a convenience function for batch processing.
func ResolveLocal ¶
ResolveLocal resolves a single local stack import to the files on disk that the stack processor would load for it. It has no side effects, never reads file contents, and never renders templates.
Semantics mirror the runtime stack processor (internal/exec ProcessImportSection and processYAMLConfigFileWithContextInternal):
- `./` and `../` import paths are relative to the importing file's directory; every other path is relative to stacksBasePath.
- An import with no extension tries `.yaml`, `.yml`, `.yaml.tmpl`, `.yml.tmpl` in that order and falls back to `.yaml`.
- An import ending in `.yaml` or `.yml` is upgraded to the `.tmpl` sibling when that file exists.
- Glob patterns (including doublestar `**`) are expanded.
Remote imports (see IsRemote) and templated paths (see IsTemplatedPath) are not handled here; callers must filter them out first.
It returns errUtils.ErrStackImportNotFound (wrapped) when nothing matches, and errUtils.ErrInvalidImport (wrapped) when the path is empty or a non-relative path is given without a stacksBasePath.
func ValidateStaticImportPath ¶
func ValidateStaticImportPath(atmosConfig *schema.AtmosConfiguration, path, manifest string) error
ValidateStaticImportPath rejects dynamic paths before optional-import handling can omit them. Invalid delimiter settings cannot establish that a path is static.
func WhenContext ¶
WhenContext returns the runtime facts available to a stack import's `when` condition: whether Atmos is running in a detected CI environment, and the process environment (exposed to CEL expressions as the `env` map). Callers add literal stack labels and tags from their current import scope. Stack, component, and command facts are not available because imports are resolved while the stack manifests are read, before any of them is known.
Types ¶
type MetadataScope ¶
type MetadataScope struct {
Before schema.StackImportMetadata
Overrides []schema.StackImportMetadata
Config *schema.AtmosConfiguration
}
MetadataScope keeps earlier defaults separate from the importing manifests' explicit metadata. Overrides remain ordered layers so structural !append tags retain their meaning in nested imports.
func (MetadataScope) Activate ¶
func (scope MetadataScope) Activate(ctx *condition.Context, imported, local schema.StackImportMetadata) error
Activate supplies the literal metadata available to the current condition.
func (MetadataScope) Child ¶
func (scope MetadataScope) Child(imported, local schema.StackImportMetadata) (MetadataScope, error)
Child snapshots the scope before an import entry; all glob matches share this snapshot.
func (MetadataScope) Merge ¶
func (scope MetadataScope) Merge(layers ...schema.StackImportMetadata) (schema.StackImportMetadata, error)
Merge combines metadata using the same list strategy as stack loading.
type RemoteImportMatch ¶
RemoteImportMatch is a resolved remote stack import ready for local processing.
func ResolveRemoteImport ¶
func ResolveRemoteImport(atmosConfig *schema.AtmosConfiguration, uri string) ([]RemoteImportMatch, error)
ResolveRemoteImport is a convenience function that uses the global importer.
func ResolveRemoteImportNested ¶
func ResolveRemoteImportNested(atmosConfig *schema.AtmosConfiguration, uri, nestedImports, ttl string) ([]RemoteImportMatch, error)
ResolveRemoteImportNested is a convenience function that uses the global importer. The ttl controls cross-run reuse of the cloned source repo for git subdir imports (see ensureSourceDir); an empty ttl refreshes the clone once per invocation.
type RemoteImporter ¶
type RemoteImporter struct {
// contains filtered or unexported fields
}
RemoteImporter handles downloading stack imports from remote URLs.
func NewRemoteImporter ¶
func NewRemoteImporter(atmosConfig *schema.AtmosConfiguration, opts ...RemoteImporterOption) (*RemoteImporter, error)
NewRemoteImporter creates a new RemoteImporter.
func (*RemoteImporter) ClearCache ¶
func (r *RemoteImporter) ClearCache() error
ClearCache removes all cached imports.
func (*RemoteImporter) Download ¶
func (r *RemoteImporter) Download(uri string) (result string, resultErr error)
Download fetches a remote import and returns the local path. Downloads are cached by URL hash to avoid redundant downloads. Uses file locking and atomic writes for safe concurrent access.
Honors the same atmosConfig.Imports.TTL default Resolve does. An empty ttl preserves this cache's historical behavior: once downloaded, a URL is reused indefinitely within this cache directory (no expiry) until the cache is cleared. A non-empty ttl instead expires the cached content after ttl, matching the freshness semantics ensureSourceDir uses for git-subdir imports, so the same setting governs both caching mechanisms.
func (*RemoteImporter) Resolve ¶
func (r *RemoteImporter) Resolve(uri string) ([]RemoteImportMatch, error)
Resolve fetches a remote import and returns all local stack files it resolves to.
Honors the global atmosConfig.Imports.TTL default (the same setting stack-manifest imports fall back to via ResolveRemoteImportNested) for cross-run reuse of the cloned source repo; an unset TTL refreshes the clone once per invocation, as before.
func (*RemoteImporter) ResolveNested ¶
func (r *RemoteImporter) ResolveNested(uri, nestedImports string) ([]RemoteImportMatch, error)
ResolveNested fetches a remote import and returns all local stack files it resolves to, preserving remote source context when nested imports should resolve remotely.
The cached source clone is refreshed on every invocation (no cross-run reuse); use ResolveRemoteImportNested with a TTL when cross-run cache reuse is desired.
type RemoteImporterOption ¶
type RemoteImporterOption func(*RemoteImporter)
RemoteImporterOption is a functional option for configuring RemoteImporter.
func WithCache ¶
func WithCache(c *cache.FileCache) RemoteImporterOption
WithCache sets a custom FileCache (useful for testing).
func WithDownloader ¶
func WithDownloader(d downloader.FileDownloader) RemoteImporterOption
WithDownloader sets a custom downloader (useful for testing).
Source Files