partial

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Jul 31, 2023 License: Apache-2.0 Imports: 13 Imported by: 90

README

partial

GoDoc

Partial Implementations

There are roughly two kinds of image representations: compressed and uncompressed.

The implementations for these kinds of images are almost identical, with the only major difference being how blobs (config and layers) are fetched. This common code lives in this package, where you provide a partial implementation of a compressed or uncompressed image, and you get back a full v1.Image implementation.

Examples

In a registry, blobs are compressed, so it's easiest to implement a v1.Image in terms of compressed layers. remote.remoteImage does this by implementing CompressedImageCore:

type CompressedImageCore interface {
	RawConfigFile() ([]byte, error)
	MediaType() (types.MediaType, error)
	RawManifest() ([]byte, error)
	LayerByDigest(v1.Hash) (CompressedLayer, error)
}

In a tarball, blobs are (often) uncompressed, so it's easiest to implement a v1.Image in terms of uncompressed layers. tarball.uncompressedImage does this by implementing UncompressedImageCore:

type UncompressedImageCore interface {
	RawConfigFile() ([]byte, error)
	MediaType() (types.MediaType, error)
	LayerByDiffID(v1.Hash) (UncompressedLayer, error)
}

Optional Methods

Where possible, we access some information via optional methods as an optimization.

partial.Descriptor

There are some properties of a Descriptor that aren't derivable from just image data:

  • MediaType
  • Platform
  • URLs
  • Annotations

For example, in a tarball.Image, there is a LayerSources field that contains an entire layer descriptor with URLs information for foreign layers. This information can be passed through to callers by implementing this optional Descriptor method.

See #654.

partial.UncompressedSize

Usually, you don't need to know the uncompressed size of a layer, since that information isn't stored in a config file (just he sha256 is needed); however, there are cases where it is very helpful to know the layer size, e.g. when writing the uncompressed layer into a tarball.

See #655.

partial.Exists

We generally don't care about the existence of something as granular as a layer, and would rather ensure all the invariants of an image are upheld via the validate package. However, there are situations where we want to do a quick smoke test to ensure that the underlying storage engine hasn't been corrupted by something e.g. deleting files or blobs. Thus, we've exposed an optional Exists method that does an existence check without actually reading any bytes.

The remote package implements this via HEAD requests.

The layout package implements this via os.Stat.

See #838.

Documentation

Overview

Package partial defines methods for building up a v1.Image from minimal subsets that are sufficient for defining a v1.Image.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ArtifactType added in v0.14.0

func ArtifactType(w WithManifest) (string, error)

ArtifactType returns the artifact type for the given manifest.

If the manifest reports its own artifact type, that's returned, otherwise the manifest is parsed and, if successful, its config.mediaType is returned.

func BlobDescriptor

func BlobDescriptor(i WithManifest, h v1.Hash) (*v1.Descriptor, error)

BlobDescriptor is a helper for implementing v1.Image

func BlobSize

func BlobSize(i WithManifest, h v1.Hash) (int64, error)

BlobSize is a helper for implementing v1.Image

func BlobToDiffID

func BlobToDiffID(i WithManifestAndConfigFile, h v1.Hash) (v1.Hash, error)

BlobToDiffID is a helper for mapping between compressed and uncompressed blob hashes.

func CompressedToImage

func CompressedToImage(cic CompressedImageCore) (v1.Image, error)

CompressedToImage fills in the missing methods from a CompressedImageCore so that it implements v1.Image

func CompressedToLayer

func CompressedToLayer(ul CompressedLayer) (v1.Layer, error)

CompressedToLayer fills in the missing methods from a CompressedLayer so that it implements v1.Layer

func ConfigFile

func ConfigFile(i WithRawConfigFile) (*v1.ConfigFile, error)

ConfigFile is a helper for implementing v1.Image

func ConfigLayer

func ConfigLayer(i WithRawConfigFile) (v1.Layer, error)

ConfigLayer implements v1.Layer from the raw config bytes. This is so that clients (e.g. remote) can access the config as a blob.

Images that want to return a specific layer implementation can implement withConfigLayer.

func ConfigName

func ConfigName(i WithRawConfigFile) (v1.Hash, error)

ConfigName is a helper for implementing v1.Image

func Descriptor

func Descriptor(d Describable) (*v1.Descriptor, error)

Descriptor returns a v1.Descriptor given a Describable. It also encodes some logic for unwrapping things that have been wrapped by CompressedToLayer, UncompressedToLayer, CompressedToImage, or UncompressedToImage.

func DiffIDToBlob

func DiffIDToBlob(wm WithManifestAndConfigFile, h v1.Hash) (v1.Hash, error)

DiffIDToBlob is a helper for mapping between uncompressed and compressed blob hashes.

func DiffIDs

func DiffIDs(i WithConfigFile) ([]v1.Hash, error)

DiffIDs is a helper for implementing v1.Image

func Digest

func Digest(i WithRawManifest) (v1.Hash, error)

Digest is a helper for implementing v1.Image

func Exists added in v0.5.1

func Exists(l v1.Layer) (bool, error)

Exists checks to see if a layer exists. This is a hack to work around the mistakes of the partial package. Don't use this.

func FSLayers

func FSLayers(i WithManifest) ([]v1.Hash, error)

FSLayers is a helper for implementing v1.Image

func FindImages added in v0.2.0

func FindImages(index v1.ImageIndex, matcher match.Matcher) ([]v1.Image, error)

FindImages given a v1.ImageIndex, find the images that fit the matcher. If a Descriptor matches the provider Matcher, but the referenced item is not an Image, ignores it. Only returns those that match the Matcher and are images.

func FindIndexes added in v0.2.0

func FindIndexes(index v1.ImageIndex, matcher match.Matcher) ([]v1.ImageIndex, error)

FindIndexes given a v1.ImageIndex, find the indexes that fit the matcher. If a Descriptor matches the provider Matcher, but the referenced item is not an Index, ignores it. Only returns those that match the Matcher and are indexes.

func FindManifests added in v0.2.0

func FindManifests(index v1.ImageIndex, matcher match.Matcher) ([]v1.Descriptor, error)

FindManifests given a v1.ImageIndex, find the manifests that fit the matcher.

func Manifest

func Manifest(i WithRawManifest) (*v1.Manifest, error)

Manifest is a helper for implementing v1.Image

func RawConfigFile

func RawConfigFile(i WithConfigFile) ([]byte, error)

RawConfigFile is a helper for implementing v1.Image

func RawManifest

func RawManifest(i WithManifest) ([]byte, error)

RawManifest is a helper for implementing v1.Image

func Size

func Size(i WithRawManifest) (int64, error)

Size is a helper for implementing v1.Image

func UncompressedSize

func UncompressedSize(l v1.Layer) (int64, error)

UncompressedSize returns the size of the Uncompressed layer. If the underlying implementation doesn't implement UncompressedSize directly, this will compute the uncompressedSize by reading everything returned by Compressed(). This is potentially expensive and may consume the contents for streaming layers.

func UncompressedToImage

func UncompressedToImage(uic UncompressedImageCore) (v1.Image, error)

UncompressedToImage fills in the missing methods from an UncompressedImageCore so that it implements v1.Image.

func UncompressedToLayer

func UncompressedToLayer(ul UncompressedLayer) (v1.Layer, error)

UncompressedToLayer fills in the missing methods from an UncompressedLayer so that it implements v1.Layer

Types

type CompressedImageCore

type CompressedImageCore interface {
	ImageCore

	// RawManifest returns the serialized bytes of the manifest.
	RawManifest() ([]byte, error)

	// LayerByDigest is a variation on the v1.Image method, which returns
	// a CompressedLayer instead.
	LayerByDigest(v1.Hash) (CompressedLayer, error)
}

CompressedImageCore represents the base minimum interface a natively compressed image must implement for us to produce a v1.Image.

type CompressedLayer

type CompressedLayer interface {
	// Digest returns the Hash of the compressed layer.
	Digest() (v1.Hash, error)

	// Compressed returns an io.ReadCloser for the compressed layer contents.
	Compressed() (io.ReadCloser, error)

	// Size returns the compressed size of the Layer.
	Size() (int64, error)

	// Returns the mediaType for the compressed Layer
	MediaType() (types.MediaType, error)
}

CompressedLayer represents the bare minimum interface a natively compressed layer must implement for us to produce a v1.Layer

type Describable

type Describable interface {
	Digest() (v1.Hash, error)
	MediaType() (types.MediaType, error)
	Size() (int64, error)
}

Describable represents something for which we can produce a v1.Descriptor.

func ComputeManifests added in v0.15.0

func ComputeManifests(idx v1.ImageIndex) ([]Describable, error)

ComputeManifests provides a fallback implementation for Manifests.

func Manifests added in v0.15.0

func Manifests(idx v1.ImageIndex) ([]Describable, error)

Manifests is analogous to v1.Image.Layers in that it allows values in the returned list to be lazily evaluated, which enables an index to contain an image that contains a streaming layer.

This should have been part of the v1.ImageIndex interface, but wasn't. It is instead usable through this extension interface.

type ImageCore

type ImageCore interface {
	// RawConfigFile returns the serialized bytes of this image's config file.
	RawConfigFile() ([]byte, error)

	// MediaType of this image's manifest.
	MediaType() (types.MediaType, error)
}

ImageCore is the core set of properties without which we cannot build a v1.Image

type UncompressedImageCore

type UncompressedImageCore interface {
	ImageCore

	// LayerByDiffID is a variation on the v1.Image method, which returns
	// an UncompressedLayer instead.
	LayerByDiffID(v1.Hash) (UncompressedLayer, error)
}

UncompressedImageCore represents the bare minimum interface a natively uncompressed image must implement for us to produce a v1.Image

type UncompressedLayer

type UncompressedLayer interface {
	// DiffID returns the Hash of the uncompressed layer.
	DiffID() (v1.Hash, error)

	// Uncompressed returns an io.ReadCloser for the uncompressed layer contents.
	Uncompressed() (io.ReadCloser, error)

	// Returns the mediaType for the compressed Layer
	MediaType() (types.MediaType, error)
}

UncompressedLayer represents the bare minimum interface a natively uncompressed layer must implement for us to produce a v1.Layer

type WithConfigFile

type WithConfigFile interface {
	// ConfigFile returns this image's config file.
	ConfigFile() (*v1.ConfigFile, error)
}

WithConfigFile defines the subset of v1.Image used by these helper methods

type WithDiffID

type WithDiffID interface {
	DiffID() (v1.Hash, error)
}

WithDiffID defines the subset of v1.Layer for exposing the DiffID method.

type WithManifest

type WithManifest interface {
	// Manifest returns this image's Manifest object.
	Manifest() (*v1.Manifest, error)
}

WithManifest defines the subset of v1.Image used by these helper methods

type WithManifestAndConfigFile

type WithManifestAndConfigFile interface {
	WithConfigFile

	// Manifest returns this image's Manifest object.
	Manifest() (*v1.Manifest, error)
}

WithManifestAndConfigFile defines the subset of v1.Image used by these helper methods

type WithRawConfigFile

type WithRawConfigFile interface {
	// RawConfigFile returns the serialized bytes of this image's config file.
	RawConfigFile() ([]byte, error)
}

WithRawConfigFile defines the subset of v1.Image used by these helper methods

type WithRawManifest

type WithRawManifest interface {
	// RawManifest returns the serialized bytes of this image's config file.
	RawManifest() ([]byte, error)
}

WithRawManifest defines the subset of v1.Image used by these helper methods

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL