update

Documentation

Overview

Package update is the ImageSource adapter: an HTTPS update-server client and a local-directory source, both exposing verified content-addressed assets through the build.ImageSource port.

Every acquisition failure — index fetch, metadata validation, download, cache read, checksum/size mismatch, handle open, release-metadata fetch/structural validation — wraps ErrFetch. Callers map it to process exit code 5.

The sentinel itself lives in internal/errdefs so that internal/build can wrap the same value for GPT-probe drift without importing this package; ErrFetch is the package-local name for errdefs.ErrFetch.

Index

• Variables
• func ValidateFilename(filename string) error
• func ValidateSHA256(digest string) error
• func ValidateVersion(version string) error
• type HTTPSSource
  • func NewHTTPSSource(serverURL, cacheDir string, reporter build.Reporter, client *http.Client) (*HTTPSSource, error)
  • func (s *HTTPSSource) Asset(ctx context.Context, version string, file apiimages.UpdateFile) (build.VerifiedAsset, error)
  • func (s *HTTPSSource) Index(ctx context.Context) (apiimages.Index, error)
  • func (s *HTTPSSource) ReleaseMetadata(ctx context.Context, version string, selected []apiimages.UpdateFile) (build.ReleaseMetadata, error)
• type LocalSource
  • func NewLocalSource(dir, cacheDir string, reporter build.Reporter) (*LocalSource, error)
  • func (s *LocalSource) Asset(ctx context.Context, version string, file apiimages.UpdateFile) (build.VerifiedAsset, error)
  • func (s *LocalSource) Index(ctx context.Context) (apiimages.Index, error)
  • func (s *LocalSource) ReleaseMetadata(ctx context.Context, version string, selected []apiimages.UpdateFile) (build.ReleaseMetadata, error)

Variables

var ErrFetch = errdefs.ErrFetch

ErrFetch is returned when acquiring or reading an update-server artifact fails. Every acquisition failure in this adapter wraps it. Callers map it to process exit code 5. It is the package-local name for errdefs.ErrFetch; errors.Is matches through either.

Functions

func ValidateFilename

func ValidateFilename(filename string) error

ValidateFilename returns an error unless filename is a legal untrusted UpdateFile.Filename value. It must be a non-empty relative path whose '/' segments each pass the same allowlist as ValidateVersion, with empty, ".", and ".." segments rejected. Callers must invoke this before using filename as a URL or filesystem path.

func ValidateSHA256

func ValidateSHA256(digest string) error

ValidateSHA256 returns an error unless digest is exactly 64 lowercase hex characters. Callers must invoke this before using the digest as a cache path component.

func ValidateVersion

func ValidateVersion(version string) error

ValidateVersion returns an error unless version is a legal untrusted UpdateFull.Version value. It must be non-empty, match [A-Za-z0-9._-]+, and must not be "." or "..". Callers must invoke this before using version as a URL or filesystem path.

Types

type HTTPSSource

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

HTTPSSource is an ImageSource that fetches from an HTTPS update server and retains verified assets in a content-addressed cache.

func NewHTTPSSource

func NewHTTPSSource(serverURL, cacheDir string, reporter build.Reporter, client *http.Client) (*HTTPSSource, error)

NewHTTPSSource constructs an HTTPS ImageSource for serverURL. serverURL must use the https scheme (plain http is rejected at construction). cacheDir is the content-addressed cache root. reporter receives download progress; it must be non-nil. client may be nil, in which case a default http.Client with no overall timeout is used (cancellation is via ctx).

func (*HTTPSSource) Asset

func (s *HTTPSSource) Asset(
	ctx context.Context,
	version string,
	file apiimages.UpdateFile,
) (build.VerifiedAsset, error)

Asset validates version/filename/sha256/size, then reuses or downloads the file into the content-addressed cache and returns a VerifiedAsset. Downloads retry the fetch+admit pair (3 attempts, 100ms jittered backoff, ctx-cancellable) so a dropped body is retried; a checksum/size mismatch gets exactly one clean re-download, then fails with the admission wording.

func (*HTTPSSource) Index

func (s *HTTPSSource) Index(ctx context.Context) (apiimages.Index, error)

Index fetches <server>/index.json, capped at 64 MiB, and decodes it as apiimages.Index.

func (*HTTPSSource) ReleaseMetadata

func (s *HTTPSSource) ReleaseMetadata(
	ctx context.Context,
	version string,
	selected []apiimages.UpdateFile,
) (build.ReleaseMetadata, error)

ReleaseMetadata fetches update.json and update.sjson from /<version>/, validates them structurally, and returns the HTTP bodies verbatim.

type LocalSource

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

LocalSource is an ImageSource rooted at a local mirror directory with the same layout as the HTTPS server: <dir>/index.json and <dir>/<version>/<filename>. Assets are verified (size+hash) on admission into the same content-addressed cache used by HTTPSSource, then served from that immutable entry so a later write to the mirror cannot change bytes behind an already-issued handle.

func NewLocalSource

func NewLocalSource(dir, cacheDir string, reporter build.Reporter) (*LocalSource, error)

NewLocalSource constructs a directory ImageSource rooted at dir. cacheDir is the content-addressed cache root (shared layout with HTTPS). reporter must be non-nil.

func (*LocalSource) Asset

func (s *LocalSource) Asset(
	ctx context.Context,
	version string,
	file apiimages.UpdateFile,
) (build.VerifiedAsset, error)

Asset validates version/filename/sha256/size, then admits <dir>/<version>/<filename> into the cache and returns a VerifiedAsset.

func (*LocalSource) Index

func (s *LocalSource) Index(ctx context.Context) (apiimages.Index, error)

Index reads <dir>/index.json, capped at 64 MiB, and decodes it as apiimages.Index.

func (*LocalSource) ReleaseMetadata

func (s *LocalSource) ReleaseMetadata(
	ctx context.Context,
	version string,
	selected []apiimages.UpdateFile,
) (build.ReleaseMetadata, error)

ReleaseMetadata reads update.json and update.sjson from <dir>/<version>/, validates them structurally, and returns the file bytes verbatim.