partial

package
v0.20.2 Latest Latest
Warning

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

 Go to latest Published: Aug 6, 2024 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

Source Files

View all Source files

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.