diff

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: May 1, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package diff defines the on-disk delta archive sidecar schema and the pure data types shared by the exporter and importer.

The package is intentionally free of I/O and framework dependencies: it can be vendored by a third-party tool that only needs to read or generate diffah-compatible sidecars.

Key types:

Forward-compat rules for the sidecar schema and the registry-error classification surface in this package are documented in docs/compat.md at the repository root.

Package diff defines the domain types and contracts shared by the exporter and importer services. It depends only on the standard library and on stable container-spec types (digest, BlobInfo).

Index

Constants

View Source 
const FeatureBundle = "bundle"
View Source 
const SchemaVersionV1 = "v1"
View Source 
const SidecarFilename = "diffah.json"

Variables

This section is empty.

Functions

func ClassifyRegistryErr added in v0.2.0 

func ClassifyRegistryErr(err error, ref string) error

ClassifyRegistryErr maps upstream registry errors to diffah typed error types that carry the correct exit-code category. When the error is not recognised as registry-related, the original error is returned unchanged so the existing errs.Classify fallbacks still apply.

Case ordering is deliberate: auth is checked first so that a message like "unauthorized: manifest not found" classifies as auth (the actionable root cause) rather than a missing manifest.

func IsRetryableRegistryErr added in v0.2.0 

func IsRetryableRegistryErr(err error) bool

IsRetryableRegistryErr reports whether err carries a transient upstream signal — HTTP 429/5xx, network reset, EOF, or a wrapped *url.Error / *net.OpError. Permanent failures (401/403 auth, 404 manifest, manifest schema errors) return false so retry loops fail fast.

Types

type BaselineRef 

type BaselineRef struct {
	ManifestDigest digest.Digest `json:"manifest_digest"`
	MediaType      string        `json:"media_type"`
	SourceHint     string        `json:"source_hint,omitempty"`
}

type BaselineSpec added in v0.2.0 

type BaselineSpec struct {
	Baselines map[string]string `json:"baselines"`
}

func ParseBaselineSpec added in v0.2.0 

func ParseBaselineSpec(path string) (*BaselineSpec, error)

type BlobEntry added in v0.2.0 

type BlobEntry struct {
	Size            int64         `json:"size"`
	MediaType       string        `json:"media_type"`
	Encoding        Encoding      `json:"encoding"`
	Codec           string        `json:"codec,omitempty"`
	PatchFromDigest digest.Digest `json:"patch_from_digest,omitempty"`
	ArchiveSize     int64         `json:"archive_size"`
}

type BlobRef 

type BlobRef struct {
	Digest    digest.Digest `json:"digest"`
	Size      int64         `json:"size"`
	MediaType string        `json:"media_type"`

	Encoding        Encoding      `json:"encoding,omitempty"`
	Codec           string        `json:"codec,omitempty"`
	PatchFromDigest digest.Digest `json:"patch_from_digest,omitempty"`
	ArchiveSize     int64         `json:"archive_size,omitempty"`
}

BlobRef is the canonical description of a layer or config blob referenced from a manifest.

The Encoding/Codec/PatchFromDigest/ArchiveSize fields apply to ShippedInDelta entries only. RequiredFromBaseline entries omit them entirely — those layers are fetched from baseline as-is, so an archive-level encoding concept does not apply.

type BundlePairSpec added in v0.2.0 

type BundlePairSpec struct {
	Name     string `json:"name"`
	Baseline string `json:"baseline"`
	Target   string `json:"target"`
}

type BundleSpec added in v0.2.0 

type BundleSpec struct {
	Pairs []BundlePairSpec `json:"pairs"`
}

func ParseBundleSpec added in v0.2.0 

func ParseBundleSpec(path string) (*BundleSpec, error)

type Encoding added in v0.2.0 

type Encoding string

Encoding discriminates how a shipped blob is stored in the archive. The zero value ("") is invalid for ShippedInDelta entries and must not be present on RequiredFromBaseline entries. 

const (
	// EncodingFull: the archive file stored under Digest contains the
	// target blob bytes verbatim.
	EncodingFull Encoding = "full"
	// EncodingPatch: the archive file contains a codec-specific patch that
	// reconstructs the target when applied to PatchFromDigest.
	EncodingPatch Encoding = "patch"
)

type ErrBaselineBlobDigestMismatch added in v0.2.0 

type ErrBaselineBlobDigestMismatch struct {
	ImageName string
	Digest    string
	Got       string
}

ErrBaselineBlobDigestMismatch reports that a baseline-served blob's computed sha256 did not match the digest the sidecar expected. Bytes are never written to the output when this fires.

func (*ErrBaselineBlobDigestMismatch) Category added in v0.2.0 

func (*ErrBaselineBlobDigestMismatch) Category() errs.Category

func (*ErrBaselineBlobDigestMismatch) Error added in v0.2.0 

func (e *ErrBaselineBlobDigestMismatch) Error() string

type ErrBaselineMismatch added in v0.2.0 

type ErrBaselineMismatch struct{ Name, Expected, Got string }

func (*ErrBaselineMismatch) Category added in v0.2.0 

func (*ErrBaselineMismatch) Category() errs.Category

func (*ErrBaselineMismatch) Error added in v0.2.0 

func (e *ErrBaselineMismatch) Error() string

func (*ErrBaselineMismatch) NextAction added in v0.2.0 

func (*ErrBaselineMismatch) NextAction() string

type ErrBaselineMissing added in v0.2.0 

type ErrBaselineMissing struct{ Names []string }

func (*ErrBaselineMissing) Category added in v0.2.0 

func (*ErrBaselineMissing) Category() errs.Category

func (*ErrBaselineMissing) Error added in v0.2.0 

func (e *ErrBaselineMissing) Error() string

func (*ErrBaselineMissing) NextAction added in v0.2.0 

func (*ErrBaselineMissing) NextAction() string

type ErrBaselineMissingBlob 

type ErrBaselineMissingBlob struct{ Digest, Source string }

ErrBaselineMissingBlob is returned when a digest that the delta requires from baseline cannot be resolved against the provided baseline source.

func (*ErrBaselineMissingBlob) Category added in v0.2.0 

func (*ErrBaselineMissingBlob) Category() errs.Category

func (*ErrBaselineMissingBlob) Error 

func (e *ErrBaselineMissingBlob) Error() string

func (*ErrBaselineMissingBlob) NextAction added in v0.2.0 

func (*ErrBaselineMissingBlob) NextAction() string

type ErrBaselineMissingPatchRef added in v0.2.0 

type ErrBaselineMissingPatchRef struct{ Digest, Source string }

ErrBaselineMissingPatchRef is the patch-specific sibling of ErrBaselineMissingBlob. Raised when a shipped layer with encoding=patch names a patch_from_digest that is absent from the provided baseline.

func (*ErrBaselineMissingPatchRef) Category added in v0.2.0 

func (*ErrBaselineMissingPatchRef) Category() errs.Category

func (*ErrBaselineMissingPatchRef) Error added in v0.2.0 

func (e *ErrBaselineMissingPatchRef) Error() string

func (*ErrBaselineMissingPatchRef) NextAction added in v0.2.0 

func (*ErrBaselineMissingPatchRef) NextAction() string

type ErrBaselineNameUnknown added in v0.2.0 

type ErrBaselineNameUnknown struct {
	Name      string
	Available []string
}

func (*ErrBaselineNameUnknown) Category added in v0.2.0 

func (*ErrBaselineNameUnknown) Category() errs.Category

func (*ErrBaselineNameUnknown) Error added in v0.2.0 

func (e *ErrBaselineNameUnknown) Error() string

func (*ErrBaselineNameUnknown) NextAction added in v0.2.0 

func (*ErrBaselineNameUnknown) NextAction() string

type ErrBundleSpecMissingTransport added in v0.2.0 

type ErrBundleSpecMissingTransport struct {
	FieldPath string // e.g. "pairs[0].baseline"
	Value     string
}

ErrBundleSpecMissingTransport is returned when a BundleSpec pair's baseline or target value does not carry a transport prefix. Includes a sed migration hint that rewrites bare *.tar values to docker-archive:*.tar in place.

func (*ErrBundleSpecMissingTransport) Category added in v0.2.0 

func (*ErrBundleSpecMissingTransport) Category() errs.Category

func (*ErrBundleSpecMissingTransport) Error added in v0.2.0 

func (e *ErrBundleSpecMissingTransport) Error() string

func (*ErrBundleSpecMissingTransport) NextAction added in v0.2.0 

func (*ErrBundleSpecMissingTransport) NextAction() string

type ErrDigestMismatch 

type ErrDigestMismatch struct{ Where, Want, Got string }

ErrDigestMismatch is returned when a post-operation verification detects that the resulting digest does not match the expected one.

func (*ErrDigestMismatch) Category added in v0.2.0 

func (*ErrDigestMismatch) Category() errs.Category

func (*ErrDigestMismatch) Error 

func (e *ErrDigestMismatch) Error() string

type ErrDuplicateBundleName added in v0.2.0 

type ErrDuplicateBundleName struct{ Name string }

func (*ErrDuplicateBundleName) Category added in v0.2.0 

func (*ErrDuplicateBundleName) Category() errs.Category

func (*ErrDuplicateBundleName) Error added in v0.2.0 

func (e *ErrDuplicateBundleName) Error() string

func (*ErrDuplicateBundleName) NextAction added in v0.2.0 

func (*ErrDuplicateBundleName) NextAction() string

type ErrIncompatibleOutputFormat 

type ErrIncompatibleOutputFormat struct{ SourceMime, OutputFormat string }

ErrIncompatibleOutputFormat is returned when the requested --output-format conflicts with the source manifest media type in a way diffah cannot reconcile without explicit user intent.

func (*ErrIncompatibleOutputFormat) Category added in v0.2.0 

func (*ErrIncompatibleOutputFormat) Category() errs.Category

func (*ErrIncompatibleOutputFormat) Error 

func (e *ErrIncompatibleOutputFormat) Error() string

func (*ErrIncompatibleOutputFormat) NextAction added in v0.2.0 

func (*ErrIncompatibleOutputFormat) NextAction() string

type ErrIntraLayerAssemblyMismatch added in v0.2.0 

type ErrIntraLayerAssemblyMismatch struct{ Digest, Got string }

ErrIntraLayerAssemblyMismatch reports that a patched layer's computed sha256 did not match the manifest-declared digest. Import must fail fast with no partial output.

func (*ErrIntraLayerAssemblyMismatch) Category added in v0.2.0 

func (*ErrIntraLayerAssemblyMismatch) Category() errs.Category

func (*ErrIntraLayerAssemblyMismatch) Error added in v0.2.0 

func (e *ErrIntraLayerAssemblyMismatch) Error() string

type ErrIntraLayerUnsupported added in v0.2.0 

type ErrIntraLayerUnsupported struct{ Reason string }

ErrIntraLayerUnsupported is raised on the exporter side when the current options make intra-layer mode impossible (e.g. baseline is manifest-only with no blob bytes).

func (*ErrIntraLayerUnsupported) Category added in v0.2.0 

func (*ErrIntraLayerUnsupported) Category() errs.Category

func (*ErrIntraLayerUnsupported) Error added in v0.2.0 

func (e *ErrIntraLayerUnsupported) Error() string

func (*ErrIntraLayerUnsupported) NextAction added in v0.2.0 

func (*ErrIntraLayerUnsupported) NextAction() string

type ErrInvalidBundleFormat added in v0.2.0 

type ErrInvalidBundleFormat struct{ Cause error }

func (*ErrInvalidBundleFormat) Category added in v0.2.0 

func (*ErrInvalidBundleFormat) Category() errs.Category

func (*ErrInvalidBundleFormat) Error added in v0.2.0 

func (e *ErrInvalidBundleFormat) Error() string

func (*ErrInvalidBundleFormat) Unwrap added in v0.2.0 

func (e *ErrInvalidBundleFormat) Unwrap() error

type ErrInvalidBundleSpec added in v0.2.0 

type ErrInvalidBundleSpec struct {
	Path   string
	Reason string
}

func (*ErrInvalidBundleSpec) Category added in v0.2.0 

func (*ErrInvalidBundleSpec) Category() errs.Category

func (*ErrInvalidBundleSpec) Error added in v0.2.0 

func (e *ErrInvalidBundleSpec) Error() string

func (*ErrInvalidBundleSpec) NextAction added in v0.2.0 

func (*ErrInvalidBundleSpec) NextAction() string

type ErrManifestListUnselected 

type ErrManifestListUnselected struct{ Ref string }

ErrManifestListUnselected is returned when the caller passes a manifest list but does not specify --platform to select an instance.

func (*ErrManifestListUnselected) Category added in v0.2.0 

func (*ErrManifestListUnselected) Category() errs.Category

func (*ErrManifestListUnselected) Error 

func (e *ErrManifestListUnselected) Error() string

func (*ErrManifestListUnselected) NextAction added in v0.2.0 

func (*ErrManifestListUnselected) NextAction() string

type ErrMultiImageNeedsNamedBaselines added in v0.2.0 

type ErrMultiImageNeedsNamedBaselines struct{ N int }

func (*ErrMultiImageNeedsNamedBaselines) Category added in v0.2.0 

func (*ErrMultiImageNeedsNamedBaselines) Category() errs.Category

func (*ErrMultiImageNeedsNamedBaselines) Error added in v0.2.0 

func (e *ErrMultiImageNeedsNamedBaselines) Error() string

func (*ErrMultiImageNeedsNamedBaselines) NextAction added in v0.2.0 

func (*ErrMultiImageNeedsNamedBaselines) NextAction() string

type ErrNotADiffahArchive added in v0.2.0 

type ErrNotADiffahArchive struct{ Path string }

ErrNotADiffahArchive is returned when a file that was expected to be a diffah delta archive is opened but does not contain the sidecar JSON. Classified as content because the file — if it existed and was readable — simply is not a diffah artifact.

func (*ErrNotADiffahArchive) Category added in v0.2.0 

func (*ErrNotADiffahArchive) Category() errs.Category

func (*ErrNotADiffahArchive) Error added in v0.2.0 

func (e *ErrNotADiffahArchive) Error() string

func (*ErrNotADiffahArchive) NextAction added in v0.2.0 

func (*ErrNotADiffahArchive) NextAction() string

type ErrPhase1Archive added in v0.2.0 

type ErrPhase1Archive struct{ GotFeature string }

func (*ErrPhase1Archive) Category added in v0.2.0 

func (*ErrPhase1Archive) Category() errs.Category

func (*ErrPhase1Archive) Error added in v0.2.0 

func (e *ErrPhase1Archive) Error() string

func (*ErrPhase1Archive) NextAction added in v0.2.0 

func (*ErrPhase1Archive) NextAction() string

type ErrRegistryAuth added in v0.2.0 

type ErrRegistryAuth struct{ Registry string }

ErrRegistryAuth is returned when authentication against a registry fails (401/403 or an auth-config parse error). Classified as user.

func (*ErrRegistryAuth) Category added in v0.2.0 

func (*ErrRegistryAuth) Category() errs.Category

func (*ErrRegistryAuth) Error added in v0.2.0 

func (e *ErrRegistryAuth) Error() string

func (*ErrRegistryAuth) NextAction added in v0.2.0 

func (*ErrRegistryAuth) NextAction() string

type ErrRegistryManifestInvalid added in v0.2.0 

type ErrRegistryManifestInvalid struct{ Ref, Reason string }

ErrRegistryManifestInvalid is returned when a manifest body fails to parse or uses an unsupported schema. Classified as content.

func (*ErrRegistryManifestInvalid) Category added in v0.2.0 

func (*ErrRegistryManifestInvalid) Category() errs.Category

func (*ErrRegistryManifestInvalid) Error added in v0.2.0 

func (e *ErrRegistryManifestInvalid) Error() string

func (*ErrRegistryManifestInvalid) NextAction added in v0.2.0 

func (*ErrRegistryManifestInvalid) NextAction() string

type ErrRegistryManifestMissing added in v0.2.0 

type ErrRegistryManifestMissing struct{ Ref string }

ErrRegistryManifestMissing is returned when a manifest request returns 404. Classified as content.

func (*ErrRegistryManifestMissing) Category added in v0.2.0 

func (*ErrRegistryManifestMissing) Category() errs.Category

func (*ErrRegistryManifestMissing) Error added in v0.2.0 

func (e *ErrRegistryManifestMissing) Error() string

func (*ErrRegistryManifestMissing) NextAction added in v0.2.0 

func (*ErrRegistryManifestMissing) NextAction() string

type ErrRegistryNetwork added in v0.2.0 

type ErrRegistryNetwork struct {
	Op    string
	Cause error
}

ErrRegistryNetwork wraps connectivity, DNS, and timeout errors raised while talking to a registry. Classified as environment.

func (*ErrRegistryNetwork) Category added in v0.2.0 

func (*ErrRegistryNetwork) Category() errs.Category

func (*ErrRegistryNetwork) Error added in v0.2.0 

func (e *ErrRegistryNetwork) Error() string

func (*ErrRegistryNetwork) NextAction added in v0.2.0 

func (*ErrRegistryNetwork) NextAction() string

func (*ErrRegistryNetwork) Unwrap added in v0.2.0 

func (e *ErrRegistryNetwork) Unwrap() error

type ErrShippedBlobDigestMismatch added in v0.2.0 

type ErrShippedBlobDigestMismatch struct {
	ImageName string
	Digest    string
	Got       string
}

ErrShippedBlobDigestMismatch reports that a bundle-shipped blob's computed sha256 did not match the digest recorded in the sidecar. This indicates bundle corruption or a writer bug.

func (*ErrShippedBlobDigestMismatch) Category added in v0.2.0 

func (*ErrShippedBlobDigestMismatch) Category() errs.Category

func (*ErrShippedBlobDigestMismatch) Error added in v0.2.0 

func (e *ErrShippedBlobDigestMismatch) Error() string

type ErrSidecarSchema 

type ErrSidecarSchema struct{ Reason string }

ErrSidecarSchema wraps a sidecar JSON decoding or validation failure.

func (*ErrSidecarSchema) Category added in v0.2.0 

func (*ErrSidecarSchema) Category() errs.Category

func (*ErrSidecarSchema) Error 

func (e *ErrSidecarSchema) Error() string

func (*ErrSidecarSchema) NextAction added in v0.2.0 

func (*ErrSidecarSchema) NextAction() string

type ErrSourceManifestUnreadable 

type ErrSourceManifestUnreadable struct {
	Ref   string
	Cause error
}

ErrSourceManifestUnreadable is returned when the target manifest cannot be fetched or parsed.

func (*ErrSourceManifestUnreadable) Category added in v0.2.0 

func (e *ErrSourceManifestUnreadable) Category() errs.Category

func (*ErrSourceManifestUnreadable) Error 

func (e *ErrSourceManifestUnreadable) Error() string

func (*ErrSourceManifestUnreadable) Unwrap 

func (e *ErrSourceManifestUnreadable) Unwrap() error

type ErrUnknownBundleVersion added in v0.2.0 

type ErrUnknownBundleVersion struct{ Got string }

func (*ErrUnknownBundleVersion) Category added in v0.2.0 

func (*ErrUnknownBundleVersion) Category() errs.Category

func (*ErrUnknownBundleVersion) Error added in v0.2.0 

func (e *ErrUnknownBundleVersion) Error() string

func (*ErrUnknownBundleVersion) NextAction added in v0.2.0 

func (*ErrUnknownBundleVersion) NextAction() string

type ErrUnknownImageFormat added in v0.2.0 

type ErrUnknownImageFormat struct{ Got string }

ErrUnknownImageFormat is returned when the caller passes a value to the --image-format flag that is not one of the supported image formats (docker-archive, oci-archive, dir).

func (*ErrUnknownImageFormat) Category added in v0.2.0 

func (*ErrUnknownImageFormat) Category() errs.Category

func (*ErrUnknownImageFormat) Error added in v0.2.0 

func (e *ErrUnknownImageFormat) Error() string

func (*ErrUnknownImageFormat) NextAction added in v0.2.0 

func (*ErrUnknownImageFormat) NextAction() string

type ImageEntry added in v0.2.0 

type ImageEntry struct {
	Name     string      `json:"name"`
	Baseline BaselineRef `json:"baseline"`
	Target   TargetRef   `json:"target"`
}

type OutputSpec added in v0.2.0 

type OutputSpec struct {
	Outputs map[string]string `json:"outputs"`
}

OutputSpec is the parsed form of an OUTPUT-SPEC JSON file used by 'diffah unbundle' to map each image name in the bundle to a fully- qualified transport-prefixed destination reference.

func ParseOutputSpec added in v0.2.0 

func ParseOutputSpec(path string) (*OutputSpec, error)

ParseOutputSpec reads a JSON file of the form: 

{"outputs": {"<name>": "<transport>:<path-or-url>", ...}}

Every value must carry a transport prefix accepted by go.podman.io/image/v5/transports/alltransports. Returns *ErrInvalidBundleSpec on any shape/content failure.

type Plan 

type Plan struct {
	ShippedInDelta       []BlobRef
	RequiredFromBaseline []BlobRef
}

Plan records the outcome of ComputePlan: which target layers must be resolved from baseline at import time, and which must be shipped inside the delta archive.

func ComputePlan 

func ComputePlan(target []BlobRef, baseline []digest.Digest) Plan

ComputePlan partitions target into RequiredFromBaseline and ShippedInDelta according to which digests already exist in baseline.

Order within each partition follows the target's original order so that manifest layer ordering can be preserved downstream.

type Sidecar 

type Sidecar struct {
	Version     string                      `json:"version"`
	Feature     string                      `json:"feature"`
	Tool        string                      `json:"tool"`
	ToolVersion string                      `json:"tool_version"`
	CreatedAt   time.Time                   `json:"created_at"`
	Platform    string                      `json:"platform"`
	Blobs       map[digest.Digest]BlobEntry `json:"blobs"`
	Images      []ImageEntry                `json:"images"`
}

func ParseSidecar 

func ParseSidecar(raw []byte) (*Sidecar, error)

func (Sidecar) Marshal 

func (s Sidecar) Marshal() ([]byte, error)

func (Sidecar) RequiresZstd added in v0.2.0 

func (s Sidecar) RequiresZstd() bool

RequiresZstd reports whether this archive contains at least one intra-layer patch payload. Importers and inspectors use this to decide whether the zstd binary is required at import time.

type TargetRef added in v0.2.0 

type TargetRef struct {
	ManifestDigest digest.Digest `json:"manifest_digest"`
	ManifestSize   int64         `json:"manifest_size"`
	MediaType      string        `json:"media_type"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package errs classifies errors into categories that determine exit codes and user-facing hints.
 Package errs classifies errors into categories that determine exit codes and user-facing hints.

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.