Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidImageID   = errors.New("invalid image ID")
	ErrBlankImageID     = errors.Wrap(ErrInvalidImageID, "blank image name")
	ErrMalformedImageID = errors.Wrap(ErrInvalidImageID, `expected image name as either <image>:<tag> or just <image>`)
)

Functions

func NewerByCreated

func NewerByCreated(lhs, rhs *Info) bool

NewerByCreated returns true if lhs image should be sorted before rhs with regard to their creation date descending.

func NewerBySemver

func NewerBySemver(lhs, rhs *Info) bool

NewerBySemver returns true if lhs image should be sorted before rhs with regard to their semver order descending.

func Sort

func Sort(infos []Info, newer func(a, b *Info) bool)

Sort orders the given image infos according to `newer` func.

Types

type CanonicalName

type CanonicalName struct {
	Name
}

CanonicalName is an image name with none of the fields left to be implied by convention.

type CanonicalRef

type CanonicalRef struct {
	Ref
}

CanonicalRef is an image ref with none of the fields left to be implied by convention.

type Info

type Info struct {
	// the reference to this image; probably a tagged image name
	ID Ref `json:",omitempty"`
	// the digest we got when fetching the metadata, which will be
	// different each time a manifest is uploaded for the reference
	Digest string `json:",omitempty"`
	// an identifier for the *image* this reference points to; this
	// will be the same for references that point at the same image
	// (but does not necessarily equal Docker's image ID)
	ImageID string `json:",omitempty"`
	// all labels we are interested in and could find for the image ref
	Labels Labels `json:",omitempty"`
	// the time at which the image pointed at was created
	CreatedAt time.Time `json:",omitempty"`
	// the last time this image manifest was fetched
	LastFetched time.Time `json:",omitempty"`
}

Info has the metadata we are able to determine about an image ref, from its registry.

func (Info) MarshalJSON

func (im Info) MarshalJSON() ([]byte, error)

MarshalJSON returns the Info value in JSON (as bytes). It is implemented so that we can omit the `CreatedAt` value when it's zero, which would otherwise be tricky for e.g., JavaScript to detect.

func (*Info) UnmarshalJSON

func (im *Info) UnmarshalJSON(b []byte) error

UnmarshalJSON populates an Info from JSON (as bytes). It's the companion to MarshalJSON above.

type LabelTimestampFormatError

type LabelTimestampFormatError struct {
	Labels []string
}

func (*LabelTimestampFormatError) Error

func (e *LabelTimestampFormatError) Error() string

type Labels

type Labels struct {
	// BuildDate holds the Label Schema spec 'build date' label
	// Ref: http://label-schema.org/rc1/#build-time-labels
	BuildDate time.Time `json:"org.label-schema.build-date,omitempty"`
	// Created holds the Open Container Image spec 'created' label
	// Ref: https://github.com/opencontainers/image-spec/blob/master/annotations.md#pre-defined-annotation-keys
	Created time.Time `json:"org.opencontainers.image.created,omitempty"`
}

Labels has all the image labels we are interested in for an image ref, the JSON struct tag keys should be equal to the label.

func (Labels) MarshalJSON

func (l Labels) MarshalJSON() ([]byte, error)

MarshalJSON returns the Labels value in JSON (as bytes). It is implemented so that we can omit the time values when they are zero, which would otherwise be tricky for e.g., JavaScript to detect.

func (*Labels) UnmarshalJSON

func (l *Labels) UnmarshalJSON(b []byte) error

UnmarshalJSON populates Labels from JSON (as bytes). It's the companion to MarshalJSON above.

type Name

type Name struct {
	Domain, Image string
}

Name represents an unversioned (i.e., untagged) image a.k.a., an image repo. These sometimes include a domain, e.g., quay.io, and always include a path with at least one element. By convention, images at DockerHub may have the domain omitted; and, if they only have single path element, the prefix `library` is implied.

Examples (stringified):

* alpine
* library/alpine
* docker.io/fluxcd/flux
* localhost:5000/arbitrary/path/to/repo

func (Name) CanonicalName

func (i Name) CanonicalName() CanonicalName

CanonicalName returns the canonicalised registry host and image parts of the ID.

func (Name) Registry

func (i Name) Registry() string

Registry returns the domain name of the Docker image registry, to use to fetch the image or image metadata.

func (Name) Repository

func (i Name) Repository() string

Repository returns the canonicalised path part of an Name.

func (Name) String

func (i Name) String() string

func (Name) ToRef

func (i Name) ToRef(tag string) Ref

type Ref

type Ref struct {
	Name
	Tag string
	SHA string
}

Ref represents a versioned (i.e., tagged) image. The tag is allowed to be empty, though it is in general undefined what that means. As such, `Ref` also includes all `Name` values.

Examples (stringified):

* alpine:3.5
* library/alpine:3.5
* docker.io/fluxcd/flux:1.1.0
* localhost:5000/arbitrary/path/to/repo:revision-sha1

func ParseRef

func ParseRef(s string) (Ref, error)

ParseRef parses a string representation of an image id into an Ref value. The grammar is shown here: https://github.com/docker/distribution/blob/master/reference/reference.go (but we do not care about all the productions.)

func (Ref) CanonicalRef

func (i Ref) CanonicalRef() CanonicalRef

CanonicalRef returns the canonicalised reference including the tag if present.

func (Ref) Components

func (i Ref) Components() (domain, repo, tag string)

func (Ref) MarshalJSON

func (i Ref) MarshalJSON() ([]byte, error)

ImageID is serialized/deserialized as a string

func (Ref) String

func (i Ref) String() string

String returns the Ref as a string (i.e., unparsed) without canonicalising it.

func (*Ref) UnmarshalJSON

func (i *Ref) UnmarshalJSON(data []byte) (err error)

ImageID is serialized/deserialized as a string

func (Ref) WithNewTag

func (i Ref) WithNewTag(t string) Ref

WithNewTag makes a new copy of an ImageID with a new tag

type RepositoryMetadata

type RepositoryMetadata struct {
	Tags   []string        // all the tags found in the repository
	Images map[string]Info // indexed by `Tags`, but may not include keys for all entries in `Tags`
}

RepositoryMetadata contains the image metadata information found in an image repository.

`Images` is indexed by `Tags`. Note that `Images` may be partial/incomplete, (i.e. entries from `Tags` may not have a corresponding key in `Images`), this indicates that the tag manifest was missing or corrupted in the repository.

func (RepositoryMetadata) FindImageWithRef

func (rm RepositoryMetadata) FindImageWithRef(ref Ref) Info

FindImageWithRef returns image.Info given an image ref. If the image cannot be found, it returns the image.Info with the ID provided.

func (RepositoryMetadata) GetImageTagInfo

func (rm RepositoryMetadata) GetImageTagInfo() ([]Info, error)

GetImageTagInfo gets the information of all image tags. If there are tags missing information, an error is returned

Source Files