templatesource

Documentation

Overview

Package render implements the template rendering related subcommands.

Index

• type DownloadMetadata
• type Downloader
  • func ForUpgrade(ctx context.Context, f *ForUpgradeParams) (Downloader, error)
  • func ParseSource(ctx context.Context, params *ParseSourceParams) (Downloader, error)
• type DownloaderVars
• type ForUpgradeParams
• type LocalDownloader
  • func (l *LocalDownloader) Download(ctx context.Context, cwd, templateDir, destDir string) (*DownloadMetadata, error)
• type LocationType
• type ParseSourceParams

Types

type DownloadMetadata

type DownloadMetadata struct {
	// A "canonical" location is one that's the same for everybody. When
	// installing a template source like
	// "~/my_downloaded_templates/foo_template", that location is not canonical,
	// because not every has that directory downloaded on their machine. On the
	// other hand, a template location like
	// github.com/abcxyz/gcp-org-terraform-template *is* canonical because
	// everyone everywhere can access it by that name.
	//
	// Canonical template locations are preferred because they make automatic
	// template upgrades easier. Given a destination directory that is the
	// output of a template, we can easily upgrade it if we know the canonical
	// location of the template that created it. We just go look for new git
	// tags at the canonical location.
	//
	// A local template directory is not a canonical location except for one
	// special case: when the template source directory and the destination
	// directory are within the same repo. This supports the case where a single
	// git repo contains templates that are rendered into that repo. Since the
	// relative path between the template directory and the destination
	// directory are the same for everyone who clones the repo, that means the
	// relative path counts as a canonical source.
	//
	// IsCanonical is true if and only if CanonicalSource and LocationType are
	// non-empty.
	IsCanonical     bool
	CanonicalSource string
	LocationType    LocationType

	// Depending on where the template was taken from, there might be a version
	// string associated with it (e.g. a git tag or a git SHA). May be empty.
	// This field does not use the magic string "latest" which is used
	// elsewhere; by the time this field is set, the "latest" version has been
	// resolved to a specific concrete version.
	Version string

	// Either the special string "latest", or the name of a branch to use to
	// upgrade from in the future. "latest" means the same thing as it does
	// when passed on the render command line: find the latest semver tag.
	UpgradeChannel string

	// Values for template variables like _git_tag and _git_sha.
	Vars DownloaderVars
}

type Downloader

type Downloader interface {
	// Download downloads this template into templateDir. templateDir should be
	// a temporary directory.
	//
	// destDir is the directory that this operation is targeting, from the
	// user's point of view. This is only used to determine whether a template
	// installed from a local directory is canonical or not; it's not written to
	// as part of the download operation. When we're being called as part of
	// `abc render`, then this is the render output directory. When
	// we're being called as part of `abc upgrade`, this is the
	// directory that the template is installed to, and NOT the temp dir that
	// receives the output of Render().
	Download(ctx context.Context, cwd, templateDir, destDir string) (*DownloadMetadata, error)
}

A Downloader is returned by a sourceParser. It offers the ability to download a template, and provides some metadata.

func ForUpgrade

func ForUpgrade(ctx context.Context, f *ForUpgradeParams) (Downloader, error)

ForUpgrade takes a location type and canonical location from a manifest file, and returns a downloader that will download the latest version of that template.

func ParseSource

func ParseSource(ctx context.Context, params *ParseSourceParams) (Downloader, error)

ParseSource maps the input template source to a particular kind of source (e.g. git) and returns a downloader that will download that source.

source is a template location, like "github.com/foo/bar@v1.2.3". protocol is the value of the --protocol flag, like "https".

A list of sourceParsers is accepted as input for the purpose of testing, rather than hardcoding the real list of sourceParsers.

type DownloaderVars

type DownloaderVars struct {
	GitTag      string
	GitSHA      string
	GitShortSHA string
}

Values for template variables like _git_tag and _git_sha.

type ForUpgradeParams

type ForUpgradeParams struct {
	// InstalledDir is the directory where the template was rendered to, and is
	// now being upgraded.
	InstalledDir string

	// CanonicalLocation is the location of the template source, e.g.
	// github.com/abcxyz/abc/t/foo .
	CanonicalLocation string

	// One of local_git, remote_git, etc.
	LocType LocationType

	// The value of --git-protocol.
	GitProtocol string

	// The version to update to; may be the magic string "latest", a tag, a
	// branch, or a SHA.
	Version string

	// Optional: the value of the UpgradeChannel to be returned in the
	// DownloadMetadata of the returned Downloader. This can come from the
	// --upgrade-channel or from the manifest being upgraded. Leave empty to
	// autodetect the upgrade channel based on the Version field.
	UpgradeChannel string
}

ForUpgradeParams contains the arguments to ForUpgrade().

type LocalDownloader

type LocalDownloader struct {
	// This path uses the OS-native file separator and is an absolute path.
	SrcPath string
}

LocalDownloader implements Downloader.

func (*LocalDownloader) Download

func (l *LocalDownloader) Download(ctx context.Context, cwd, templateDir, destDir string) (*DownloadMetadata, error)

installedDir is only used to check for canonical-ness.

type LocationType

type LocationType string

LocationType is an enum describing where we got a template from.

const (
	Latest = "latest"

	LocalNonGit LocationType = "local" // local never appears in a manifest, because only canonical template sources appear in a manifest
	LocalGit    LocationType = "local_git"
	RemoteGit   LocationType = "remote_git"
)

type ParseSourceParams

type ParseSourceParams struct {
	// The working directory that we're in. Used to resolve relative paths.
	CWD string

	// Source could be any of the template source types we accept. Examples:
	//  - github.com/foo/bar@latest
	//  - /a/local/path
	//  - a/relative/path
	//
	// In the case where the source is a local filesystem path, it uses native
	// filesystem separators.
	Source string

	// The value of --git-protocol.
	FlagGitProtocol string

	// The value of --upgrade-channel.
	FlagUpgradeChannel string

	// Reject the user input with an error in the case where an upgrade channel
	// can't be determined from the combination of the location string and
	// flags.
	RequireUpgradeChannel bool
}

ParseSourceParams contains the arguments to ParseSource.