utils

package
v0.42.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package utils is for commonly used functions.

Package utils is for commonly used functions

Index

Constants

View Source
const (
	// TmpPathPrefix is the shared prefix used for all temporary directories
	TmpPathPrefix = "cargoship-"

	// ReadWriteExecuteUser is used for any directory or executable not normally used by the end user or containing sensitive data
	ReadWriteExecuteUser = 0700
)
View Source
const CacheDir = "cargoship"

CacheDir is the subdirectory name used under the OS user cache directory for cargoship's shared cache.

Variables

This section is empty.

Functions

func CacheMember added in v0.40.0

func CacheMember(ctx context.Context, archiveDigest, extractPath, src string)

CacheMember copies the extracted member at src into the shared cache, so the next build takes it from there rather than fetching and decompressing the archive again.

A failure to cache is not a failure to build: the member is already staged, and the only cost is doing this work again next time.

func CachedArchive added in v0.39.0

func CachedArchive(ctx context.Context, src, baseName string) (string, error)

CachedArchive returns the path to the archive at src inside the shared file cache, downloading it there first if it is not already present. The returned path is the cache entry itself, so a caller extracting from it reads the cache in place rather than copying a multi-hundred-megabyte archive to use it once.

It exists because an archive carrying an extractPath file declares no digest of its own: with extractPath set, the file's Shasum is the digest of the extracted member, not of the archive it came out of, so the shasum-keyed cache behind DownloadToFileWithChecksum has no key to store one under. This keys on the resolved URL instead.

A cached archive is therefore trusted on its URL rather than on its content, which is weaker than what this repository does everywhere else and is worth stating rather than leaving for a reader to notice. What makes it safe enough is that the member extracted from the archive is still checked against the shasum the definition declares, so a bad entry here cannot produce a bad package -- and where a definition declares no shasum, the extracted file is equally unverified whether or not the archive came from a cache, so nothing is weakened relative to fetching it every time.

func CachedMember added in v0.40.0

func CachedMember(ctx context.Context, archiveDigest, extractPath string) (string, bool)

CachedMember returns the path to the cached copy of the member at extractPath inside the archive with the given content digest, and whether there was one.

func DownloadToCache

func DownloadToCache(ctx context.Context, url, relPath string, expectedSha256 ...string) (string, error)

DownloadToCache downloads a URL into the given relative path under cargoship's cache directory if not already cached. If expectedSha256 is provided (optional), it validates that the cached or downloaded file matches the sha256 checksum.

func DownloadToFile

func DownloadToFile(ctx context.Context, src, dst string) (err error)

DownloadToFile downloads a given URL to the target filepath (including the cosign key if necessary). When src contains an inline checksum in the form URL@sha256, that checksum is used. For struct-based callers, prefer DownloadToFileWithChecksum.

func DownloadToFileWithChecksum

func DownloadToFileWithChecksum(ctx context.Context, src, dst, checksum, cacheBaseName string) (err error)

DownloadToFileWithChecksum downloads src to dst, using checksum (if non-empty) for validation and caching. checksum SHOULD come from structured config (e.g. ZarfFile.Shasum) rather than being encoded into src.

func FilterDebianLinux

func FilterDebianLinux(h *cluster.Host) bool

FilterDebianLinux is a function used to filter whether a host is a Debian based OS

func FilterEngineAlreadyPopulated

func FilterEngineAlreadyPopulated(h *cluster.Host) bool

FilterEngineAlreadyPopulated is a function used to filter whether a host already has distro files populated

func FilterEnterpriseLinux

func FilterEnterpriseLinux(h *cluster.Host) bool

FilterEnterpriseLinux is a function used to filter whether a host is an Enterprise Linux OS

func HumanBytes added in v0.39.0

func HumanBytes(n int64) string

HumanBytes formats a byte count in the MiB-style units the rest of this project reports sizes in, so a prune's output can be compared with the binary size budget and with du.

func IdentifySource

func IdentifySource(src string) (string, error)

IdentifySource returns the source type for the given source string.

func IsDebianLinux

func IsDebianLinux(con os.Configurer) bool

IsDebianLinux is true if the os.Configurer is of a type of Debian based OS

func IsEnterpriseLinux

func IsEnterpriseLinux(con os.Configurer) bool

IsEnterpriseLinux is true if the os.Configurer is of a type of Enterprise Linux

func MakeTempDir

func MakeTempDir(basePath string) (string, error)

MakeTempDir creates a temp directory with the zarf- prefix.

func ParseChecksum

func ParseChecksum(src string) (string, string, error)

ParseChecksum splits an inline checksum off the end of a source string, of the form URL@checksum. A single '@' is left alone when the URL parses with userinfo (user@host), so a credential embedded in the URL is never mistaken for a checksum suffix.

func ParseRetryAfter

func ParseRetryAfter(value string) time.Duration

ParseRetryAfter parses the Retry-After header value into a duration. It supports both delay-seconds (integer) and HTTP-date formats.

func RandomString

func RandomString(length int) (string, error)

RandomString returns a string of hexadecimal characters of a given length that is cryptographically secure, or an error

func ReadByteStrict

func ReadByteStrict(data []byte, destConfig any) error

ReadByteStrict reads a byte array and tries to place it in the provided "destConfig" object.

An unknown key is an error. This reads the cargoship config file, and a misspelled key that is quietly dropped means the setting an operator wrote never takes effect -- which on an air-gapped management node is discovered after the run, not during it. It previously warned and re-parsed leniently, and because the warning went through a throwaway logger built before the real one existed, in practice nothing was printed at all.

goccy annotates the returned error with the line and column, so the caller has somewhere to point the operator.

func ResolveCachePath

func ResolveCachePath(cachePath string) (string, error)

ResolveCachePath returns cachePath if non-empty, otherwise falls back to filepath.Join(os.UserCacheDir(), "cargoship") which respects XDG_CACHE_HOME on Linux.

Types

type CacheArea added in v0.39.0

type CacheArea struct {
	Name string
	Kind CacheAreaKind
	Path string
	// Size is the total bytes beneath Path, and Entries the number of top-level entries.
	Size    int64
	Entries int
}

CacheArea describes one subdirectory of the cache root.

func CacheUsage added in v0.39.0

func CacheUsage(cachePath string) ([]CacheArea, error)

CacheUsage reports every subdirectory under the cache root with its size, so an operator can see what is there before removing any of it.

type CacheAreaKind added in v0.39.0

type CacheAreaKind int

CacheAreaKind says whether a cache directory's entries can be removed individually.

const (
	// CacheAreaFlat holds independently-keyed entries, each complete on its own, so any
	// subset can be removed and the rest still serve hits.
	CacheAreaFlat CacheAreaKind = iota
	// CacheAreaLayout holds an OCI image layout: an index naming blobs. Removing part of it
	// leaves the index pointing at blobs that are gone, so it goes all at once or not at all.
	CacheAreaLayout
	// CacheAreaRecord holds records of runs rather than fetched content. Nothing regenerates
	// one, so pruning never touches it.
	CacheAreaRecord
)

type PruneOptions added in v0.39.0

type PruneOptions struct {
	// OlderThan keeps any entry modified within this window. Zero removes everything
	// prunable, which is the only way an image layout is removed -- see CacheAreaLayout.
	OlderThan time.Duration
	// DryRun reports what would be removed without removing it.
	DryRun bool
}

PruneOptions control what CacheUsage's results PruneCache removes.

type Pruned added in v0.39.0

type Pruned struct {
	Dirs    []CacheArea
	Size    int64
	Entries int
	// SkippedLayouts names the image layouts left alone because OlderThan was set.
	SkippedLayouts []string
}

Pruned is what PruneCache removed, or would have removed under DryRun.

func PruneCache added in v0.39.0

func PruneCache(ctx context.Context, cachePath string, opts PruneOptions) (Pruned, error)

PruneCache removes cached content from the cache root and reports what went.

An age window prunes the flat caches entry by entry, which is what makes the command usable rather than nuclear: the working set of a definition under active edit stays, and the versions it has stopped naming go. An image layout cannot be pruned that way without breaking its index, so it is removed only by a full prune and is otherwise reported as skipped. Records -- the run logs, and the dev fleet's base images -- are never touched.

Directories

Path Synopsis
Package build is the build flag logic shared across mage and the CLI
Package build is the build flag logic shared across mage and the CLI

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL