diff

Documentation

Overview

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
• type BaselineRef
• type BlobRef
• type ErrBaselineMissingBlob
  • func (e *ErrBaselineMissingBlob) Error() string
• type ErrDigestMismatch
  • func (e *ErrDigestMismatch) Error() string
• type ErrIncompatibleOutputFormat
  • func (e *ErrIncompatibleOutputFormat) Error() string
• type ErrManifestListUnselected
  • func (e *ErrManifestListUnselected) Error() string
• type ErrSidecarSchema
  • func (e *ErrSidecarSchema) Error() string
• type ErrSourceManifestUnreadable
  • func (e *ErrSourceManifestUnreadable) Error() string
  • func (e *ErrSourceManifestUnreadable) Unwrap() error
• type ErrUnsupportedSchemaVersion
  • func (e *ErrUnsupportedSchemaVersion) Error() string
• type ImageRef
• type Plan
  • func ComputePlan(target []BlobRef, baseline []digest.Digest) Plan
• type Sidecar
  • func ParseSidecar(raw []byte) (*Sidecar, error)
  • func (s Sidecar) Marshal() ([]byte, error)

Constants

const SchemaVersionV1 = "v1"

SchemaVersionV1 is the sidecar schema version this package writes and accepts.

const SidecarFilename = "diffah.json"

SidecarFilename is the canonical file name of the sidecar written at the top level of every delta archive.

Types

type BaselineRef

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

BaselineRef describes the baseline image manifest pointer recorded in a sidecar. SourceHint is informational only.

type BlobRef

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

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

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) Error

func (e *ErrBaselineMissingBlob) Error() 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) Error

func (e *ErrDigestMismatch) Error() 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) Error

func (e *ErrIncompatibleOutputFormat) Error() 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) Error

func (e *ErrManifestListUnselected) Error() string

type ErrSidecarSchema

type ErrSidecarSchema struct{ Reason string }

ErrSidecarSchema wraps a sidecar JSON decoding or validation failure.

func (*ErrSidecarSchema) Error

func (e *ErrSidecarSchema) Error() string

type ErrSourceManifestUnreadable

type ErrSourceManifestUnreadable struct {
	Ref   string
	Cause error
}

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

func (*ErrSourceManifestUnreadable) Error

func (e *ErrSourceManifestUnreadable) Error() string

func (*ErrSourceManifestUnreadable) Unwrap

func (e *ErrSourceManifestUnreadable) Unwrap() error

type ErrUnsupportedSchemaVersion

type ErrUnsupportedSchemaVersion struct{ Got string }

ErrUnsupportedSchemaVersion is returned when a sidecar's version is not recognized by the current reader.

func (*ErrUnsupportedSchemaVersion) Error

func (e *ErrUnsupportedSchemaVersion) Error() string

type ImageRef

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

ImageRef describes the target image manifest pointer recorded in a sidecar.

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"`
	Tool                 string      `json:"tool"`
	ToolVersion          string      `json:"tool_version"`
	CreatedAt            time.Time   `json:"created_at"`
	Platform             string      `json:"platform"`
	Target               ImageRef    `json:"target"`
	Baseline             BaselineRef `json:"baseline"`
	RequiredFromBaseline []BlobRef   `json:"required_from_baseline"`
	ShippedInDelta       []BlobRef   `json:"shipped_in_delta"`
}

Sidecar is the diffah.json file written inside every delta archive.

It serves three purposes: schema versioning (Version), fail-fast verification (RequiredFromBaseline is probed at import time), and human inspection (ShippedInDelta plus size fields let `diffah inspect` report savings without scanning the archive).

func ParseSidecar

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

ParseSidecar decodes sidecar bytes and validates required fields and the schema version. The returned *Sidecar is safe to inspect only if err is nil.

func (Sidecar) Marshal

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

Marshal encodes the sidecar with two-space indentation. It validates the payload before writing so an invalid Sidecar cannot be persisted.