deps

package
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: Jun 12, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package deps downloads, verifies, and reports status for local VM dependencies.

Index

Constants

View Source 
const (
	TemplateChartTypeOCI   = "oci"
	TemplateChartTypeChart = "chart"
)
View Source 
const DefaultKind = "knc"

DefaultKind is the default instance kind used by the deps download command.

View Source 
const ImageDepName = "os-image"

ImageDepName is the canonical name used for the OS image dependency. It is also used as the cache subdirectory for the image file (so the image lands at <depsCacheDir>/vmconfig/artifacts/os-image/<version>/<filename>).

View Source 
const OS = "debian-13"

OS is the OS name encoded in the vmconfig manifest filename.

View Source 
const VMConfigDepName = "vmconfig"

VMConfigDepName is the canonical dependency name for the vmconfig package tarball. Unreleased manifests generated in vmconfig/manifests contain a stub for this entry; release publishing fills in its URL and digest.

Variables

View Source 
var (
	ErrNotCached  = errors.New("manifest not cached")
	ErrIncomplete = errors.New("deps cache incomplete or corrupt")
)

Sentinel errors returned by Verify so callers can distinguish "user just hasn't downloaded yet" from "the cache is corrupted" from real errors.

Functions

func PopulateComponentsZotStore 

func PopulateComponentsZotStore(ctx context.Context, destDir string, manifest *ComponentsManifest, progress func(DownloadEvent)) error

PopulateComponentsZotStore downloads component images and writes zot's repository-local OCI layout directly under destDir.

Types

type BootArtifact 

type BootArtifact struct {
	Partition int    `json:"partition"`
	Path      string `json:"path"`
	Digest    string `json:"digest"`
}

BootArtifact identifies a file inside the cached OS image.

func (BootArtifact) Valid 

func (b BootArtifact) Valid() bool

Valid reports whether this boot artifact points at a specific image file.

type BootInfo 

type BootInfo struct {
	Cmdline string       `json:"cmdline"`
	Kernel  BootArtifact `json:"kernel"`
	Initrd  BootArtifact `json:"initrd"`
}

BootInfo describes explicit boot artifacts and the raw kernel command line extracted from the default boot entry for the OS image.

func (BootInfo) Complete 

func (b BootInfo) Complete() bool

Complete reports whether the manifest has enough boot metadata for direct kernel boot. It validates only shape; extraction verifies file contents.

type ComponentImage 

type ComponentImage struct {
	Component string   `json:"component"`
	Image     string   `json:"image"`
	Digest    string   `json:"digest"`
	Size      int64    `json:"size"`
	Platform  string   `json:"platform,omitempty"`
	Index     string   `json:"index,omitempty"`
	Providers []string `json:"providers,omitempty"`
	Addon     bool     `json:"addon,omitempty"`
	Cached    bool     `json:"cached,omitempty"`
}

ComponentImage describes one source image rendered by a component chart.

type ComponentImageFilter 

type ComponentImageFilter struct {
	Archs     []string
	Providers []string
	Addons    []string
}

ComponentImageFilter selects component images for download while preserving the full manifest. An empty Providers list matches provider-neutral images only; "all" matches every provider-specific image. Addon images are included only when Addons names the component or contains "all".

type Components 

type Components struct {
	Version string           `json:"version"`
	Images  []ComponentImage `json:"images"`
}

Components lists rendered component chart images.

type ComponentsManifest 

type ComponentsManifest struct {
	Components Components `json:"components"`
}

ComponentsManifest is the top-level structure of the manifest generated by podplane/components.

func (*ComponentsManifest) DownloadImageIndexes 

func (m *ComponentsManifest) DownloadImageIndexes(filter ComponentImageFilter) []int

DownloadImageIndexes returns the indexes of component images that should be downloaded for the given architecture, provider, and addon selection. Indexes are returned instead of image copies so callers can mark local cache state on the original full manifest.

func (*ComponentsManifest) MarkCached 

func (m *ComponentsManifest) MarkCached(index int)

MarkCached marks one component image entry as present in the local cache.

func (*ComponentsManifest) ResetCached 

func (m *ComponentsManifest) ResetCached()

ResetCached clears local cache-state markers from all component images.

type Dependency 

type Dependency struct {
	Version   string   `json:"version"`
	URL       string   `json:"url"`
	Type      string   `json:"type"`
	Digest    string   `json:"digest"`
	Size      int64    `json:"size"`
	Providers []string `json:"providers,omitempty"`
	Cached    bool     `json:"cached,omitempty"`
}

Dependency describes a single downloadable artifact (binary, archive, deb, or qcow2 image) referenced by the manifest.

func (Dependency) DigestHex 

func (d Dependency) DigestHex() string

DigestHex returns just the hex portion of the digest (strips the algo: prefix). Panics if digest is malformed — callers must validate first.

func (Dependency) Filename 

func (d Dependency) Filename() string

Filename returns the base filename from the dependency URL (the last path segment), e.g. "runc" from "https://example.com/runc/v1.2.3/runc".

func (Dependency) ParseDigest 

func (d Dependency) ParseDigest() (algo string, hex string, err error)

ParseDigest returns the algorithm name and hex checksum from the Digest field. It returns an error if the digest is missing, malformed, or uses an unsupported algorithm. Supported algorithms: sha256, sha512.

func (Dependency) SHA256 

func (d Dependency) SHA256() (string, error)

SHA256 returns the hex sha256 portion of the Digest. It returns an error if the digest is missing or uses any algorithm other than sha256. Deprecated: prefer ParseDigest which supports multiple algorithms.

type DownloadEvent 

type DownloadEvent struct {
	Type    DownloadEventType
	Name    string
	Path    string
	Message string
	Current int64
	Total   int64
	Err     error
}

DownloadEvent reports progress for a single dependency artifact, or a top-level status message when Name is empty.

type DownloadEventType 

type DownloadEventType string

DownloadEventType describes a dependency download progress event. 

const (
	DownloadEventStatus   DownloadEventType = "status"
	DownloadEventChecking DownloadEventType = "checking"
	DownloadEventCached   DownloadEventType = "cached"
	DownloadEventQueued   DownloadEventType = "queued"
	DownloadEventStarted  DownloadEventType = "started"
	DownloadEventProgress DownloadEventType = "progress"
	DownloadEventDone     DownloadEventType = "done"
	DownloadEventFailed   DownloadEventType = "failed"
)

type DownloadOptions 

type DownloadOptions struct {
	DryRun      bool
	Concurrency int
	Client      *http.Client
	Progress    func(DownloadEvent)
	Output      io.Writer
	Archs       []string
	Providers   []string
	Addons      []string

	// SkipCrossArchDependencies skips dependency cache population shared across
	// VMConfig architectures, such as component images, template charts, and seed
	// snapshots. It is used by callers downloading multiple archs after the first
	// arch has already populated those shared caches.
	SkipCrossArchDependencies bool

	// SkipSeeds skips loading and caching seed manifests and snapshots.
	SkipSeeds bool

	// VMConfigManifestPath, when set, reads the vmconfig manifest from this
	// local JSON file instead of fetching it from the configured deps base URL.
	VMConfigManifestPath string

	// ComponentsManifestPath, when set, reads the components manifest from this
	// local JSON file instead of fetching it from the configured deps base URL.
	ComponentsManifestPath string

	// TemplatesManifestPath, when set, reads the templates manifest from this
	// local JSON file instead of fetching it from the configured deps base URL.
	TemplatesManifestPath string

	// SeedsManifestPath, when set, reads the seeds manifest from this local JSON
	// file instead of fetching it from the configured deps base URL.
	SeedsManifestPath string
}

DownloadOptions controls dependency download behavior.

type Item 

type Item struct {
	Name string
	Dep  Dependency
}

Item pairs a dependency with its name (the OS image uses ImageDepName). It is the unit returned by Manifest.Items.

func (Item) IsUnreleasedVMConfigStub 

func (it Item) IsUnreleasedVMConfigStub() bool

IsUnreleasedVMConfigStub reports whether item is the placeholder vmconfig dependency found in checked-in vmconfig/manifests manifests before the release workflow substitutes the real tarball URL and digest.

func (Item) LocalFilename 

func (it Item) LocalFilename() string

LocalFilename returns the filename used when the dependency is placed in /opt/podplane/artifacts/ on the VM. The naming convention is <name>.<ext> where ext is derived from Type: binary has no extension, deb → .deb, tar.gz → .tar.gz.

func (Item) Matches 

func (it Item) Matches(filter ItemFilter) bool

Matches reports whether the item applies to the selected providers and cache state.

func (Item) ResolveURL 

func (it Item) ResolveURL(baseURL string) string

ResolveURL returns the download URL for this item. When baseURL is non-empty (local dev, air-gapped mirrors) URLs are constructed as baseURL/vmconfig/artifacts/<name>/<version>/<filename>. Otherwise the original upstream URL from the manifest is used.

type ItemFilter 

type ItemFilter struct {
	Providers  []string
	CachedOnly bool
}

ItemFilter selects manifest items by provider and cache state. An empty Providers list matches provider-neutral items only; "all" matches every provider-specific item.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager handles fetching and caching manifests and the artifacts/images they reference.

func NewManager 

func NewManager(baseURL, depsCacheDir string) *Manager

NewManager creates a new deps manager.

baseURL is the base URL used to fetch manifest files, e.g. "https://cli.podplane.dev/deps". depsCacheDir is the local deps cache root.

func (*Manager) CachedComponentsVersion added in v0.2.0 

func (m *Manager) CachedComponentsVersion() (string, error)

CachedComponentsVersion returns the version from the cached components manifest.

func (*Manager) CachedSeedSnapshotPath 

func (m *Manager) CachedSeedSnapshotPath(name, version string) (string, error)

CachedSeedSnapshotPath returns the cached .netsy path for name.

func (*Manager) CachedSeedsVersion 

func (m *Manager) CachedSeedsVersion() (string, error)

CachedSeedsVersion returns the version in the latest cached seeds manifest.

func (*Manager) CachedTemplateChart 

func (m *Manager) CachedTemplateChart(name string) (TemplateChart, string, error)

CachedTemplateChart returns the cached template chart metadata and local Helm chart archive path for name.

func (*Manager) CachedTemplateChartPath 

func (m *Manager) CachedTemplateChartPath(name string) (string, error)

CachedTemplateChartPath returns the cached Helm chart archive path for name.

func (*Manager) CheckUpdateNudge 

func (m *Manager) CheckUpdateNudge(ctx context.Context, kind, arch string) string

CheckUpdateNudge attempts to determine whether a newer manifest is available, returning a one-line nudge message for the user. It is designed to be called from a background goroutine and never returns an error: any network/parse failure is folded into a friendly message.

Behaviour:

  • Fetches the latest manifest (subject to ctx).
  • On success with a different version: returns an "update available" note and refreshes the cached manifest's mtime so we don't re-nag every start.
  • On success with the same version: refreshes mtime; returns "".
  • On failure (timeout, network error, parse error): returns a "couldn't check, manifest is N days old" note.

func (*Manager) ComponentsCacheDir 

func (m *Manager) ComponentsCacheDir() string

ComponentsCacheDir returns the component dependency-domain cache directory.

func (*Manager) ComponentsHistoricalManifestCachePath 

func (m *Manager) ComponentsHistoricalManifestCachePath(raw []byte) string

ComponentsHistoricalManifestCachePath returns an immutable historical component manifest path.

func (*Manager) ComponentsImagesCacheDir 

func (m *Manager) ComponentsImagesCacheDir() string

ComponentsImagesCacheDir returns the component OCI image cache directory.

func (*Manager) ComponentsManifestCacheDir 

func (m *Manager) ComponentsManifestCacheDir() string

ComponentsManifestCacheDir returns the component manifest cache directory.

func (*Manager) ComponentsManifestCachePath 

func (m *Manager) ComponentsManifestCachePath() string

ComponentsManifestCachePath returns the path to the cached components manifest.

func (*Manager) Download 

func (m *Manager) Download(kind, arch string, opts DownloadOptions) error

Download fetches the latest manifests and downloads any referenced vmconfig artifacts and component images into the local deps cache. The manifests are cached on success so they can be reused later.

If dryRun is true, no network downloads are performed and the manifest is not written to the cache; instead, a summary of what would be downloaded is printed. Items that are already cached (with matching sha256) are skipped in both modes — dry-run only lists files that would actually be downloaded.

func (*Manager) EnsureSeedSnapshot 

func (m *Manager) EnsureSeedSnapshot(ctx context.Context, name, version string, client *http.Client) (string, error)

EnsureSeedSnapshot returns a cached seed snapshot, downloading the seeds manifest and snapshot first when needed.

func (*Manager) EnsureSeedSnapshotsCached added in v0.2.0 

func (m *Manager) EnsureSeedSnapshotsCached(ctx context.Context) (*SeedsManifest, error)

EnsureSeedSnapshotsCached returns the cached seeds manifest after ensuring all seed snapshots referenced by it are present in the local cache.

func (*Manager) EnsureSeedsManifestCached added in v0.2.0 

func (m *Manager) EnsureSeedsManifestCached(ctx context.Context) (*SeedsManifest, error)

EnsureSeedsManifestCached returns the cached seeds manifest, fetching and caching it first when the manifest is not already present locally.

func (*Manager) EnsureVMConfigManifestCached added in v0.1.2 

func (m *Manager) EnsureVMConfigManifestCached(kind, arch string) (*Manifest, error)

EnsureVMConfigManifestCached returns the cached vmconfig manifest, fetching and caching it first when the manifest is not already present locally.

func (*Manager) IsStale 

func (m *Manager) IsStale(kind, arch string, threshold time.Duration) bool

IsStale reports whether the cached manifest is older than threshold (or missing entirely). It is a cheap, synchronous check used to gate whether CheckUpdateNudge is worth running.

func (*Manager) ReadCachedManifest 

func (m *Manager) ReadCachedManifest(kind, arch string) (*Manifest, []byte, error)

ReadCachedManifest reads and parses the cached manifest JSON. It returns (nil, nil, nil) if the cache file does not exist.

func (*Manager) ReadCachedSeedsManifest 

func (m *Manager) ReadCachedSeedsManifest() (*SeedsManifest, []byte, error)

ReadCachedSeedsManifest reads the latest cached seeds manifest.

func (*Manager) ReadCachedTemplatesManifest 

func (m *Manager) ReadCachedTemplatesManifest() (*TemplatesManifest, []byte, error)

ReadCachedTemplatesManifest reads the latest cached templates manifest.

func (*Manager) SeedSnapshotCachePath 

func (m *Manager) SeedSnapshotCachePath(name, version, filename string) string

SeedSnapshotCachePath returns the cache path for a named seed snapshot.

func (*Manager) SeedsCacheDir 

func (m *Manager) SeedsCacheDir() string

SeedsCacheDir returns the seeds dependency-domain cache directory.

func (*Manager) SeedsManifestCacheDir 

func (m *Manager) SeedsManifestCacheDir() string

SeedsManifestCacheDir returns the seeds manifest cache directory.

func (*Manager) SeedsManifestCachePath 

func (m *Manager) SeedsManifestCachePath() string

SeedsManifestCachePath returns the latest cached seeds manifest path.

func (*Manager) SeedsSnapshotsCacheDir 

func (m *Manager) SeedsSnapshotsCacheDir() string

SeedsSnapshotsCacheDir returns the cached seed snapshot directory.

func (*Manager) Status 

func (m *Manager) Status(kind, arch string) (bool, *Manifest, error)

Status fetches the latest manifest and compares it byte-for-byte against the cached copy. It returns true if the cached copy is missing or differs from the latest, and also returns the parsed latest manifest.

func (*Manager) TemplatesCacheDir 

func (m *Manager) TemplatesCacheDir() string

TemplatesCacheDir returns the templates dependency-domain cache directory.

func (*Manager) TemplatesChartsCacheDir 

func (m *Manager) TemplatesChartsCacheDir() string

TemplatesChartsCacheDir returns the cached template chart data directory.

func (*Manager) TemplatesManifestCacheDir 

func (m *Manager) TemplatesManifestCacheDir() string

TemplatesManifestCacheDir returns the templates manifest cache directory.

func (*Manager) TemplatesManifestCachePath 

func (m *Manager) TemplatesManifestCachePath() string

TemplatesManifestCachePath returns the latest cached templates manifest path.

func (*Manager) VMConfigArtifactCachePath 

func (m *Manager) VMConfigArtifactCachePath(name string, dep Dependency) string

VMConfigArtifactCachePath returns the cache path for a single named vmconfig dependency artifact, e.g. "<depsCacheDir>/vmconfig/artifacts/<name>/<version>/<basename(url)>". This is the single source of truth for where downloaded vmconfig artifacts live; both Download and Verify use it.

func (*Manager) VMConfigArtifactsCacheDir 

func (m *Manager) VMConfigArtifactsCacheDir() string

VMConfigArtifactsCacheDir returns the vmconfig artifact cache directory.

func (*Manager) VMConfigCacheDir 

func (m *Manager) VMConfigCacheDir() string

VMConfigCacheDir returns the vmconfig dependency-domain cache directory.

func (*Manager) VMConfigHistoricalManifestCachePath 

func (m *Manager) VMConfigHistoricalManifestCachePath(kind, arch string, raw []byte) string

VMConfigHistoricalManifestCachePath returns an immutable historical manifest path.

func (*Manager) VMConfigManifestCacheDir 

func (m *Manager) VMConfigManifestCacheDir() string

VMConfigManifestCacheDir returns the vmconfig manifest cache directory.

func (*Manager) VMConfigManifestCachePath 

func (m *Manager) VMConfigManifestCachePath(kind, arch string) string

VMConfigManifestCachePath returns the path to the cached vmconfig manifest JSON file, e.g. ~/.podplane/cache/deps/vmconfig/manifests/vmconfig_knc_debian-13_arm64.json.

func (*Manager) Verify 

func (m *Manager) Verify(kind, arch string) (*Manifest, error)

Verify checks that the cached manifest exists and that every dependency (including the OS image) referenced by it is present in the cache and has the expected sha256. On success it returns the parsed manifest so callers can use it without re-reading from disk.

Returns ErrNotCached if no cached manifest exists. Returns ErrIncomplete (wrapped) if any artifact is missing or has the wrong digest.

func (*Manager) WriteCachedComponentsManifest 

func (m *Manager) WriteCachedComponentsManifest(raw []byte) error

WriteCachedComponentsManifest writes historical and latest components manifest JSON bytes.

func (*Manager) WriteCachedManifest 

func (m *Manager) WriteCachedManifest(kind, arch string, raw []byte) error

WriteCachedManifest writes historical and latest manifest JSON bytes to the cache.

func (*Manager) WriteCachedSeedsManifest 

func (m *Manager) WriteCachedSeedsManifest(raw []byte) error

WriteCachedSeedsManifest writes historical and latest seeds manifests.

func (*Manager) WriteCachedTemplatesManifest 

func (m *Manager) WriteCachedTemplatesManifest(raw []byte) error

WriteCachedTemplatesManifest writes historical and latest templates manifests.

type Manifest 

type Manifest struct {
	VMConfig VMConfig `json:"vmconfig"`
}

Manifest is the top-level structure of the vmconfig manifest JSON file as published at <DepsBaseURL>/vmconfig/manifests/vmconfig_<kind>_<os>_<arch>.json.

func (*Manifest) DownloadItems 

func (m *Manifest) DownloadItems(filters ...ItemFilter) []Item

DownloadItems returns only the artifacts the CLI can fetch and verify from the manifest. Local vmconfig/manifests manifests intentionally contain an unreleased vmconfig stub with no URL or digest; the release pipeline fills those fields for published manifests. The stub is not downloadable, so local development manifests skip it while still validating every real artifact.

func (*Manifest) HasVMConfigDep 

func (m *Manifest) HasVMConfigDep(filters ...ItemFilter) bool

HasVMConfigDep reports whether the manifest includes a downloadable vmconfig package (i.e. it is present in the Dependencies map and is not an unreleased stub).

func (*Manifest) InstallItems 

func (m *Manifest) InstallItems(filters ...ItemFilter) []Item

InstallItems returns the dependencies that a running VM needs to install at boot time in deterministic order. This excludes the OS image (the VM is already running on it) and any unreleased vmconfig stubs. Stable ordering prevents semantically identical userdata from changing Nstance infra hashes.

func (*Manifest) Items 

func (m *Manifest) Items() []Item

Items returns the OS image plus every named dependency as a flat list, in no guaranteed order other than the OS image first.

func (*Manifest) MarkCached 

func (m *Manifest) MarkCached(name string)

MarkCached marks one vmconfig artifact entry as present in the local cache.

func (*Manifest) ResetCached 

func (m *Manifest) ResetCached()

ResetCached clears local cache-state markers from the OS image and all vmconfig dependencies.

type OSInfo 

type OSInfo struct {
	Name  string     `json:"name"`
	Arch  string     `json:"arch"`
	Image Dependency `json:"image"`
	Boot  BootInfo   `json:"boot"`
}

OSInfo describes the base OS, including the qcow2 image to download.

type SeedSnapshot 

type SeedSnapshot struct {
	Path   string `json:"path,omitempty"`
	URL    string `json:"url,omitempty"`
	Digest string `json:"digest,omitempty"`
	Size   int64  `json:"size,omitempty"`
	Cached bool   `json:"cached,omitempty"`
}

type Seeds 

type Seeds struct {
	Version    string                  `json:"version"`
	Components string                  `json:"components"`
	Snapshots  map[string]SeedSnapshot `json:"snapshots"`
}

type SeedsManifest 

type SeedsManifest struct {
	Seeds Seeds `json:"seeds"`
}

SeedsManifest is the top-level seed snapshot dependency manifest.

func (*SeedsManifest) MarkCached 

func (m *SeedsManifest) MarkCached(name string)

MarkCached marks one seed snapshot as present in the local cache.

func (*SeedsManifest) ResetCached 

func (m *SeedsManifest) ResetCached()

ResetCached clears local cache-state markers from seed snapshots.

type TemplateChart 

type TemplateChart struct {
	Name             string               `json:"name"`
	Version          string               `json:"version"`
	Type             string               `json:"type"`
	URL              string               `json:"url,omitempty"`
	Path             string               `json:"path,omitempty"`
	Digest           string               `json:"digest,omitempty"`
	Dependencies     TemplateDependencies `json:"dependencies,omitempty"`
	Cached           bool                 `json:"cached,omitempty"`
	ChartLayerDigest string               `json:"chartLayerDigest,omitempty"`
}

type TemplateDependencies 

type TemplateDependencies struct {
	Components []string `json:"components,omitempty"`
}

type Templates 

type Templates struct {
	Version string          `json:"version"`
	Charts  []TemplateChart `json:"charts"`
}

type TemplatesManifest 

type TemplatesManifest struct {
	Templates Templates `json:"templates"`
}

TemplatesManifest is the top-level templates dependency manifest.

func (*TemplatesManifest) MarkCached 

func (m *TemplatesManifest) MarkCached(index int, chartLayerDigest string)

MarkCached marks a template chart as cached with its chart layer digest.

func (*TemplatesManifest) ResetCached 

func (m *TemplatesManifest) ResetCached()

ResetCached clears local cache-state markers from template charts.

type VMConfig 

type VMConfig struct {
	Version      string                `json:"version"`
	Kind         string                `json:"kind"`
	OS           OSInfo                `json:"os"`
	Dependencies map[string]Dependency `json:"dependencies"`
}

VMConfig is the inner manifest payload listing the OS image and all dependencies required to build a VM of the given kind.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.