types

Documentation

Overview

Package types defines various types that have no other internal imports This allows them to be used between other packages without creating import loops

Index

• Constants
• Variables
• func MediaTypeBase(orig string) string
• type CallbackKind
  • func (k CallbackKind) String() string
• type CallbackState
• type Descriptor
  • func DescriptorListFilter(dl []Descriptor, opt MatchOpt) []Descriptor
  • func DescriptorListSearch(dl []Descriptor, opt MatchOpt) (Descriptor, error)
  • func (d Descriptor) Equal(d2 Descriptor) bool
  • func (d Descriptor) GetData() ([]byte, error)
  • func (d Descriptor) MarshalPrettyTW(tw *tabwriter.Writer, prefix string) error
  • func (d Descriptor) Match(opt MatchOpt) bool
  • func (d Descriptor) Same(d2 Descriptor) bool
• type MatchOpt
• type RateLimit

Constants

const (
	// AnnotationCreated is the annotation key for the date and time on which the image was built (date-time string as defined by RFC 3339).
	AnnotationCreated = "org.opencontainers.image.created"

	// AnnotationAuthors is the annotation key for the contact details of the people or organization responsible for the image (freeform string).
	AnnotationAuthors = "org.opencontainers.image.authors"

	// AnnotationURL is the annotation key for the URL to find more information on the image.
	AnnotationURL = "org.opencontainers.image.url"

	// AnnotationDocumentation is the annotation key for the URL to get documentation on the image.
	AnnotationDocumentation = "org.opencontainers.image.documentation"

	// AnnotationSource is the annotation key for the URL to get source code for building the image.
	AnnotationSource = "org.opencontainers.image.source"

	// AnnotationVersion is the annotation key for the version of the packaged software.
	// The version MAY match a label or tag in the source code repository.
	// The version MAY be Semantic versioning-compatible.
	AnnotationVersion = "org.opencontainers.image.version"

	// AnnotationRevision is the annotation key for the source control revision identifier for the packaged software.
	AnnotationRevision = "org.opencontainers.image.revision"

	// AnnotationVendor is the annotation key for the name of the distributing entity, organization or individual.
	AnnotationVendor = "org.opencontainers.image.vendor"

	// AnnotationLicenses is the annotation key for the license(s) under which contained software is distributed as an SPDX License Expression.
	AnnotationLicenses = "org.opencontainers.image.licenses"

	// AnnotationRefName is the annotation key for the name of the reference for a target.
	// SHOULD only be considered valid when on descriptors on `index.json` within image layout.
	AnnotationRefName = "org.opencontainers.image.ref.name"

	// AnnotationTitle is the annotation key for the human-readable title of the image.
	AnnotationTitle = "org.opencontainers.image.title"

	// AnnotationDescription is the annotation key for the human-readable description of the software packaged in the image.
	AnnotationDescription = "org.opencontainers.image.description"

	// AnnotationBaseImageDigest is the annotation key for the digest of the image's base image.
	AnnotationBaseImageDigest = "org.opencontainers.image.base.digest"

	// AnnotationBaseImageName is the annotation key for the image reference of the image's base image.
	AnnotationBaseImageName = "org.opencontainers.image.base.name"

	// AnnotationArtifactCreated is the annotation key for the date and time on which the artifact was built, conforming to RFC 3339.
	AnnotationArtifactCreated = "org.opencontainers.artifact.created"

	// AnnotationArtifactDescription is the annotation key for the human readable description for the artifact.
	AnnotationArtifactDescription = "org.opencontainers.artifact.description"

	// AnnotationReferrersFiltersApplied is the annotation key for the comma separated list of filters applied by the registry in the referrers listing.
	AnnotationReferrersFiltersApplied = "org.opencontainers.referrers.filtersApplied"
)

const (
	// MediaTypeDocker1Manifest deprecated media type for docker schema1 manifests.
	MediaTypeDocker1Manifest = "application/vnd.docker.distribution.manifest.v1+json"
	// MediaTypeDocker1ManifestSigned is a deprecated schema1 manifest with jws signing.
	MediaTypeDocker1ManifestSigned = "application/vnd.docker.distribution.manifest.v1+prettyjws"
	// MediaTypeDocker2Manifest is the media type when pulling manifests from a v2 registry.
	MediaTypeDocker2Manifest = "application/vnd.docker.distribution.manifest.v2+json"
	// MediaTypeDocker2ManifestList is the media type when pulling a manifest list from a v2 registry.
	MediaTypeDocker2ManifestList = "application/vnd.docker.distribution.manifest.list.v2+json"
	// MediaTypeDocker2ImageConfig is for the configuration json object media type.
	MediaTypeDocker2ImageConfig = "application/vnd.docker.container.image.v1+json"
	// MediaTypeOCI1Artifact EXPERIMENTAL OCI v1 artifact media type.
	MediaTypeOCI1Artifact = "application/vnd.oci.artifact.manifest.v1+json"
	// MediaTypeOCI1Manifest OCI v1 manifest media type.
	MediaTypeOCI1Manifest = "application/vnd.oci.image.manifest.v1+json"
	// MediaTypeOCI1ManifestList OCI v1 manifest list media type.
	MediaTypeOCI1ManifestList = "application/vnd.oci.image.index.v1+json"
	// MediaTypeOCI1ImageConfig OCI v1 configuration json object media type.
	MediaTypeOCI1ImageConfig = "application/vnd.oci.image.config.v1+json"
	// MediaTypeDocker2LayerGzip is the default compressed layer for docker schema2.
	MediaTypeDocker2LayerGzip = "application/vnd.docker.image.rootfs.diff.tar.gzip"
	// MediaTypeDocker2ForeignLayer is the default compressed layer for foreign layers in docker schema2.
	MediaTypeDocker2ForeignLayer = "application/vnd.docker.image.rootfs.foreign.diff.tar.gzip"
	// MediaTypeOCI1Layer is the uncompressed layer for OCIv1.
	MediaTypeOCI1Layer = "application/vnd.oci.image.layer.v1.tar"
	// MediaTypeOCI1LayerGzip is the gzip compressed layer for OCI v1.
	MediaTypeOCI1LayerGzip = "application/vnd.oci.image.layer.v1.tar+gzip"
	// MediaTypeOCI1LayerZstd is the zstd compressed layer for OCI v1.
	MediaTypeOCI1LayerZstd = "application/vnd.oci.image.layer.v1.tar+zstd"
	// MediaTypeOCI1ForeignLayer is the foreign layer for OCI v1.
	MediaTypeOCI1ForeignLayer = "application/vnd.oci.image.layer.nondistributable.v1.tar"
	// MediaTypeOCI1ForeignLayerGzip is the gzip compressed foreign layer for OCI v1.
	MediaTypeOCI1ForeignLayerGzip = "application/vnd.oci.image.layer.nondistributable.v1.tar+gzip"
	// MediaTypeOCI1ForeignLayerZstd is the zstd compressed foreign layer for OCI v1.
	MediaTypeOCI1ForeignLayerZstd = "application/vnd.oci.image.layer.nondistributable.v1.tar+zstd"
	// MediaTypeOCI1Empty is used for blobs containing the empty JSON data `{}`.
	MediaTypeOCI1Empty = "application/vnd.oci.empty.v1+json"
	// MediaTypeBuildkitCacheConfig is used by buildkit cache images.
	MediaTypeBuildkitCacheConfig = "application/vnd.buildkit.cacheconfig.v0"
)

Variables

var (
	// ErrAllRequestsFailed when there are no mirrors left to try
	ErrAllRequestsFailed = errors.New("all requests failed")
	// ErrAPINotFound if an api is not available for the host
	ErrAPINotFound = errors.New("API not found")
	// ErrBackoffLimit maximum backoff attempts reached
	ErrBackoffLimit = errors.New("backoff limit reached")
	// ErrCanceled if the context was canceled
	ErrCanceled = errors.New("context was canceled")
	// ErrDigestMismatch if the expected digest wasn't received
	ErrDigestMismatch = errors.New("digest mismatch")
	// ErrEmptyChallenge indicates an issue with the received challenge in the WWW-Authenticate header
	ErrEmptyChallenge = errors.New("empty challenge header")
	// ErrFileDeleted indicates a requested file has been deleted
	ErrFileDeleted = errors.New("file deleted")
	// ErrFileNotFound indicates a requested file is not found
	ErrFileNotFound = fmt.Errorf("file not found%.0w", fs.ErrNotExist)
	// ErrHTTPStatus if the http status code was unexpected
	ErrHTTPStatus = errors.New("unexpected http status code")
	// ErrInvalidChallenge indicates an issue with the received challenge in the WWW-Authenticate header
	ErrInvalidChallenge = errors.New("invalid challenge header")
	// ErrInvalidReference indicates the reference to an image is has an invalid syntax
	ErrInvalidReference = errors.New("invalid reference")
	// ErrLoopDetected indicates a child node points back to the parent
	ErrLoopDetected = errors.New("loop detected")
	// ErrManifestNotSet indicates the manifest is not set, it must be pulled with a ManifestGet first
	ErrManifestNotSet = errors.New("manifest not set")
	// ErrMissingAnnotation returned when a needed annotation is not found
	ErrMissingAnnotation = errors.New("annotation is missing")
	// ErrMissingDigest returned when image reference does not include a digest
	ErrMissingDigest = errors.New("digest missing from image reference")
	// ErrMissingLocation returned when the location header is missing
	ErrMissingLocation = errors.New("location header missing")
	// ErrMissingName returned when name missing for host
	ErrMissingName = errors.New("name missing")
	// ErrMissingTag returned when image reference does not include a tag
	ErrMissingTag = errors.New("tag missing from image reference")
	// ErrMissingTagOrDigest returned when image reference does not include a tag or digest
	ErrMissingTagOrDigest = errors.New("tag or Digest missing from image reference")
	// ErrMismatch returned when a comparison detects a difference
	ErrMismatch = errors.New("content does not match")
	// ErrMountReturnedLocation when a blob mount fails but a location header is received
	ErrMountReturnedLocation = errors.New("blob mount returned a location to upload")
	// ErrNoNewChallenge indicates a challenge update did not result in any change
	ErrNoNewChallenge = errors.New("no new challenge")
	// ErrNotFound isn't there, search for your value elsewhere
	ErrNotFound = errors.New("not found")
	// ErrNotImplemented returned when method has not been implemented yet
	ErrNotImplemented = errors.New("not implemented")
	// ErrParsingFailed when a string cannot be parsed
	ErrParsingFailed = errors.New("parsing failed")
	// ErrRetryNeeded indicates a request needs to be retried
	ErrRetryNeeded = errors.New("retry needed")
	// ErrShortRead if contents are less than expected the size
	ErrShortRead = errors.New("short read")
	// ErrSizeLimitExceeded if contents exceed the size limit
	ErrSizeLimitExceeded = errors.New("size limit exceeded")
	// ErrUnavailable when a requested value is not available
	ErrUnavailable = errors.New("unavailable")
	// ErrUnsupported indicates the request was unsupported
	ErrUnsupported = errors.New("unsupported")
	// ErrUnsupportedAPI happens when an API is not supported on a registry
	ErrUnsupportedAPI = errors.New("unsupported API")
	// ErrUnsupportedConfigVersion happens when config file version is greater than this command supports
	ErrUnsupportedConfigVersion = errors.New("unsupported config version")
	// ErrUnsupportedMediaType returned when media type is unknown or unsupported
	ErrUnsupportedMediaType = errors.New("unsupported media type")
)

var (
	// ErrHTTPRateLimit when requests exceed server rate limit
	ErrHTTPRateLimit = fmt.Errorf("rate limit exceeded%.0w", ErrHTTPStatus)
	// ErrHTTPUnauthorized when authentication fails
	ErrHTTPUnauthorized = fmt.Errorf("unauthorized%.0w", ErrHTTPStatus)
)

custom HTTP errors extend the ErrHTTPStatus error

var EmptyData = []byte("{}")

var EmptyDigest = digest.FromBytes(EmptyData)

Functions

func MediaTypeBase

func MediaTypeBase(orig string) string

MediaTypeBase cleans the Content-Type header to return only the lower case base media type.

Types

type CallbackKind

type CallbackKind int

const (
	CallbackManifest CallbackKind = iota
	CallbackBlob
)

func (CallbackKind) String

func (k CallbackKind) String() string

type CallbackState

type CallbackState int

const (
	CallbackUndef CallbackState = iota
	CallbackSkipped
	CallbackStarted
	CallbackActive
	CallbackFinished
	CallbackArchived
)

type Descriptor

type Descriptor struct {
	// MediaType describe the type of the content.
	MediaType string `json:"mediaType"`

	// Digest uniquely identifies the content.
	Digest digest.Digest `json:"digest"`

	// Size in bytes of content.
	Size int64 `json:"size"`

	// URLs contains the source URLs of this content.
	URLs []string `json:"urls,omitempty"`

	// Annotations contains arbitrary metadata relating to the targeted content.
	Annotations map[string]string `json:"annotations,omitempty"`

	// Data is an embedding of the targeted content. This is encoded as a base64
	// string when marshalled to JSON (automatically, by encoding/json). If
	// present, Data can be used directly to avoid fetching the targeted content.
	Data []byte `json:"data,omitempty"`

	// Platform describes the platform which the image in the manifest runs on.
	// This should only be used when referring to a manifest.
	Platform *platform.Platform `json:"platform,omitempty"`

	// ArtifactType is the media type of the artifact this descriptor refers to.
	ArtifactType string `json:"artifactType,omitempty"`
}

Descriptor is used in manifests to refer to content by media type, size, and digest.

func DescriptorListFilter

func DescriptorListFilter(dl []Descriptor, opt MatchOpt) []Descriptor

DescriptorListFilter returns a list of descriptors from the list matching the search options. When opt.SortAnnotation is set, the order of descriptors with matching annotations is undefined.

func DescriptorListSearch

func DescriptorListSearch(dl []Descriptor, opt MatchOpt) (Descriptor, error)

DescriptorListSearch returns the first descriptor from the list matching the search options

func (Descriptor) Equal

func (d Descriptor) Equal(d2 Descriptor) bool

Equal indicates the two descriptors are identical, effectively a DeepEqual.

func (Descriptor) GetData

func (d Descriptor) GetData() ([]byte, error)

GetData decodes the Data field from the descriptor if available

func (Descriptor) MarshalPrettyTW

func (d Descriptor) MarshalPrettyTW(tw *tabwriter.Writer, prefix string) error

func (Descriptor) Match

func (d Descriptor) Match(opt MatchOpt) bool

Match returns true if the descriptor matches the options, including compatible platforms

func (Descriptor) Same

func (d Descriptor) Same(d2 Descriptor) bool

Same indicates two descriptors point to the same CAS object. This verifies the digest, media type, and size all match

type MatchOpt

type MatchOpt struct {
	Platform       *platform.Platform // Platform to match including compatible platforms (darwin/arm64 matches linux/arm64)
	ArtifactType   string             // Match ArtifactType in the descriptor
	Annotations    map[string]string  // Match each of the specified annotations and their value, an empty value verifies the key is set
	SortAnnotation string             // Sort the results by an annotation, string based comparison, descriptors without the annotation are sorted last
	SortDesc       bool               // Set to true to sort in descending order
}

MatchOpt defines conditions for a match descriptor

type RateLimit

type RateLimit struct {
	Remain, Limit, Reset int
	Set                  bool
	Policies             []string
}

RateLimit is returned from some http requests