manifest

package
v5.33.0 Latest Latest
Warning

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

 Go to latest Published: Nov 8, 2024 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DockerV2Schema1MediaType MIME type represents Docker manifest schema 1
	DockerV2Schema1MediaType = "application/vnd.docker.distribution.manifest.v1+json"
	// DockerV2Schema1SignedMediaType MIME type represents Docker manifest schema 1 with a JWS signature
	DockerV2Schema1SignedMediaType = "application/vnd.docker.distribution.manifest.v1+prettyjws"
	// DockerV2Schema2MediaType MIME type represents Docker manifest schema 2
	DockerV2Schema2MediaType = "application/vnd.docker.distribution.manifest.v2+json"
	// DockerV2Schema2ConfigMediaType is the MIME type used for schema 2 config blobs.
	DockerV2Schema2ConfigMediaType = "application/vnd.docker.container.image.v1+json"
	// DockerV2Schema2LayerMediaType is the MIME type used for schema 2 layers.
	DockerV2Schema2LayerMediaType = "application/vnd.docker.image.rootfs.diff.tar.gzip"
	// DockerV2SchemaLayerMediaTypeUncompressed is the mediaType used for uncompressed layers.
	DockerV2SchemaLayerMediaTypeUncompressed = "application/vnd.docker.image.rootfs.diff.tar"
	// DockerV2ListMediaType MIME type represents Docker manifest schema 2 list
	DockerV2ListMediaType = "application/vnd.docker.distribution.manifest.list.v2+json"
	// DockerV2Schema2ForeignLayerMediaType is the MIME type used for schema 2 foreign layers.
	DockerV2Schema2ForeignLayerMediaType = "application/vnd.docker.image.rootfs.foreign.diff.tar"
	// DockerV2Schema2ForeignLayerMediaType is the MIME type used for gzipped schema 2 foreign layers.
	DockerV2Schema2ForeignLayerMediaTypeGzip = "application/vnd.docker.image.rootfs.foreign.diff.tar.gzip"
)

FIXME(runcom, mitr): should we have a mediatype pkg??

View Source 
const (
	// OCI1InstanceAnnotationCompressionZSTD is an annotation name that can be placed on a manifest descriptor in an OCI index.
	// The value of the annotation must be the string "true".
	// If this annotation is present on a manifest, consuming that image instance requires support for Zstd compression.
	// That also suggests that this instance benefits from
	// Zstd compression, so it can be preferred by compatible consumers over instances that
	// use gzip, depending on their local policy.
	OCI1InstanceAnnotationCompressionZSTD      = "io.github.containers.compression.zstd"
	OCI1InstanceAnnotationCompressionZSTDValue = "true"
)

Variables

This section is empty.

Functions

func CandidateCompressionMatchesReuseConditions added in v5.31.0 

func CandidateCompressionMatchesReuseConditions(c ReuseConditions, candidateCompression *compressiontypes.Algorithm) bool

CandidateCompressionMatchesReuseConditions returns true if a layer with candidateCompression (which can be nil to represent uncompressed or unknown) matches reuseConditions.

func CompressionAlgorithmIsUniversallySupported added in v5.30.0 

func CompressionAlgorithmIsUniversallySupported(algo compressiontypes.Algorithm) bool

CompressionAlgorithmIsUniversallySupported returns true if MIMETypeSupportsCompressionAlgorithm(mimeType, algo) returns true for all mimeType values.

func Digest added in v5.25.0 

func Digest(manifest []byte) (digest.Digest, error)

Digest returns the a digest of a docker manifest, with any necessary implied transformations like stripping v1s1 signatures. This is publicly visible as c/image/manifest.Digest.

func GuessMIMEType added in v5.25.0 

func GuessMIMEType(manifest []byte) string

GuessMIMEType guesses MIME type of a manifest and returns it _if it is recognized_, or "" if unknown or unrecognized. FIXME? We should, in general, prefer out-of-band MIME type instead of blindly parsing the manifest, but we may not have such metadata available (e.g. when the manifest is a local file). This is publicly visible as c/image/manifest.GuessMIMEType.

func MIMETypeSupportsCompressionAlgorithm added in v5.30.0 

func MIMETypeSupportsCompressionAlgorithm(mimeType string, algo compressiontypes.Algorithm) bool

MIMETypeSupportsCompressionAlgorithm returns true if mimeType can represent algo.

func MatchesDigest added in v5.25.0 

func MatchesDigest(manifest []byte, expectedDigest digest.Digest) (bool, error)

MatchesDigest returns true iff the manifest matches expectedDigest. Error may be set if this returns false. Note that this is not doing ConstantTimeCompare; by the time we get here, the cryptographic signature must already have been verified, or we are not using a cryptographic channel and the attacker can modify the digest along with the manifest blob. This is publicly visible as c/image/manifest.MatchesDigest.

func NewNonImageArtifactError 

func NewNonImageArtifactError(manifest *imgspecv1.Manifest) error

NewNonImageArtifactError returns a NonImageArtifactError about an artifact manifest.

This is typically called if manifest.Config.MediaType != imgspecv1.MediaTypeImageConfig .

func NormalizedMIMEType added in v5.25.0 

func NormalizedMIMEType(input string) string

NormalizedMIMEType returns the effective MIME type of a manifest MIME type returned by a server, centralizing various workarounds. This is publicly visible as c/image/manifest.NormalizedMIMEType.

func ValidateUnambiguousManifestFormat added in v5.25.0 

func ValidateUnambiguousManifestFormat(manifest []byte, expectedMIMEType string,
	allowed AllowedManifestFields) error

ValidateUnambiguousManifestFormat rejects manifests (incl. multi-arch) that look like more than one kind we currently recognize, i.e. if they contain any of the known “essential” format fields other than the ones the caller specifically allows. expectedMIMEType is used only for diagnostics. NOTE: The caller should do the non-heuristic validations (e.g. check for any specified format identification/version, or other “magic numbers”) before calling this, to cleanly reject unambiguous data that just isn’t what was expected, as opposed to actually ambiguous data.

Types

type AllowedManifestFields added in v5.25.0 

type AllowedManifestFields int

AllowedManifestFields is a bit mask of “essential” manifest fields that ValidateUnambiguousManifestFormat can expect to be present. 

const (
	AllowedFieldConfig AllowedManifestFields = 1 << iota
	AllowedFieldFSLayers
	AllowedFieldHistory
	AllowedFieldLayers
	AllowedFieldManifests
	AllowedFieldFirstUnusedBit // Keep this at the end!
)

type List added in v5.25.0 

type List interface {
	ListPublic
	// CloneInternal returns a deep copy of this list and its contents.
	CloneInternal() List
	// ChooseInstanceInstanceByCompression selects which manifest is most appropriate for the platform and compression described by the
	// SystemContext ( or for the current platform if the SystemContext doesn't specify any detail ) and preferGzip for compression which
	// when configured to OptionalBoolTrue and chooses best available compression when it is OptionalBoolFalse or left OptionalBoolUndefined.
	ChooseInstanceByCompression(ctx *types.SystemContext, preferGzip types.OptionalBool) (digest.Digest, error)
	// Edit information about the list's instances. Contains Slice of ListEdit where each element
	// is responsible for either Modifying or Adding a new instance to the Manifest. Operation is
	// selected on the basis of configured ListOperation field.
	EditInstances([]ListEdit) error
}

List is an interface for parsing, modifying lists of image manifests. Callers can either use this abstract interface without understanding the details of the formats, or instantiate a specific implementation (e.g. manifest.OCI1Index) and access the public members directly.

func ListFromBlob added in v5.25.0 

func ListFromBlob(manifest []byte, manifestMIMEType string) (List, error)

ListFromBlob parses a list of manifests.

type ListEdit added in v5.26.0 

type ListEdit struct {
	ListOperation ListOp

	// if Op == ListEditUpdate (basically the previous UpdateInstances). All fields must be set.
	UpdateOldDigest             digest.Digest
	UpdateDigest                digest.Digest
	UpdateSize                  int64
	UpdateMediaType             string
	UpdateAffectAnnotations     bool
	UpdateAnnotations           map[string]string
	UpdateCompressionAlgorithms []compression.Algorithm

	// If Op = ListEditAdd. All fields must be set.
	AddDigest                digest.Digest
	AddSize                  int64
	AddMediaType             string
	AddArtifactType          string
	AddPlatform              *imgspecv1.Platform
	AddAnnotations           map[string]string
	AddCompressionAlgorithms []compression.Algorithm
}

ListEdit includes the fields which a List's EditInstances() method will modify.

type ListOp added in v5.26.0 

type ListOp int
const (
	ListOpAdd ListOp
	ListOpUpdate
)

type ListPublic added in v5.25.0 

type ListPublic interface {
	// MIMEType returns the MIME type of this particular manifest list.
	MIMEType() string

	// Instances returns a list of the manifests that this list knows of, other than its own.
	Instances() []digest.Digest

	// Update information about the list's instances.  The length of the passed-in slice must
	// match the length of the list of instances which the list already contains, and every field
	// must be specified.
	UpdateInstances([]ListUpdate) error

	// Instance returns the size and MIME type of a particular instance in the list.
	Instance(digest.Digest) (ListUpdate, error)

	// ChooseInstance selects which manifest is most appropriate for the platform described by the
	// SystemContext, or for the current platform if the SystemContext doesn't specify any details.
	ChooseInstance(ctx *types.SystemContext) (digest.Digest, error)

	// Serialize returns the list in a blob format.
	// NOTE: Serialize() does not in general reproduce the original blob if this object was loaded
	// from, even if no modifications were made!
	Serialize() ([]byte, error)

	// ConvertToMIMEType returns the list rebuilt to the specified MIME type, or an error.
	ConvertToMIMEType(mimeType string) (ListPublic, error)

	// Clone returns a deep copy of this list and its contents.
	Clone() ListPublic
}

ListPublic is a subset of List which is a part of the public API; so no methods can be added, removed or changed.

Internal users should usually use List instead.

func ListPublicFromBlob added in v5.25.0 

func ListPublicFromBlob(manifest []byte, manifestMIMEType string) (ListPublic, error)

ListPublicFromBlob parses a list of manifests. This is publicly visible as c/image/manifest.ListFromBlob.

type ListUpdate added in v5.25.0 

type ListUpdate struct {
	Digest    digest.Digest
	Size      int64
	MediaType string
	// ReadOnly fields: may be set by Instance(), ignored by UpdateInstance()
	ReadOnly struct {
		Platform                  *imgspecv1.Platform
		Annotations               map[string]string
		CompressionAlgorithmNames []string
		ArtifactType              string
	}
}

ListUpdate includes the fields which a List's UpdateInstances() method will modify. This is publicly visible as c/image/manifest.ListUpdate.

type NonImageArtifactError 

type NonImageArtifactError struct {
	// contains filtered or unexported fields
}

NonImageArtifactError (detected via errors.As) is used when asking for an image-specific operation on an object which is not a “container image” in the standard sense (e.g. an OCI artifact)

This is publicly visible as c/image/manifest.NonImageArtifactError (but we don’t provide a public constructor)

func (NonImageArtifactError) Error 

func (e NonImageArtifactError) Error() string

type OCI1Index added in v5.25.0 

type OCI1Index struct {
	OCI1IndexPublic
}

func OCI1IndexFromManifest added in v5.25.0 

func OCI1IndexFromManifest(manifest []byte) (*OCI1Index, error)

OCI1IndexFromManifest creates a OCI1 manifest list instance from marshalled JSON, presumably generated by encoding a OCI1 manifest list.

func (*OCI1Index) ChooseInstanceByCompression added in v5.25.0 

func (index *OCI1Index) ChooseInstanceByCompression(ctx *types.SystemContext, preferGzip types.OptionalBool) (digest.Digest, error)

func (*OCI1Index) Clone added in v5.25.0 

func (index *OCI1Index) Clone() ListPublic

func (*OCI1Index) CloneInternal added in v5.25.0 

func (index *OCI1Index) CloneInternal() List

func (*OCI1Index) EditInstances added in v5.26.0 

func (index *OCI1Index) EditInstances(editInstances []ListEdit) error

type OCI1IndexPublic added in v5.25.0 

type OCI1IndexPublic struct {
	imgspecv1.Index
}

OCI1IndexPublic is just an alias for the OCI index type, but one which we can provide methods for. This is publicly visible as c/image/manifest.OCI1Index Internal users should usually use OCI1Index instead.

func OCI1IndexPublicClone added in v5.25.0 

func OCI1IndexPublicClone(index *OCI1IndexPublic) *OCI1IndexPublic

OCI1IndexPublicClone creates a deep copy of the passed-in index. This is publicly visible as c/image/manifest.OCI1IndexClone.

func OCI1IndexPublicFromComponents added in v5.25.0 

func OCI1IndexPublicFromComponents(components []imgspecv1.Descriptor, annotations map[string]string) *OCI1IndexPublic

OCI1IndexPublicFromComponents creates an OCI1 image index instance from the supplied data. This is publicly visible as c/image/manifest.OCI1IndexFromComponents.

func OCI1IndexPublicFromManifest added in v5.25.0 

func OCI1IndexPublicFromManifest(manifest []byte) (*OCI1IndexPublic, error)

OCI1IndexPublicFromManifest creates an OCI1 manifest index instance from marshalled JSON, presumably generated by encoding a OCI1 manifest index. This is publicly visible as c/image/manifest.OCI1IndexFromManifest.

func (*OCI1IndexPublic) ChooseInstance added in v5.25.0 

func (index *OCI1IndexPublic) ChooseInstance(ctx *types.SystemContext) (digest.Digest, error)

ChooseInstance parses blob as an oci v1 manifest index, and returns the digest of the image which is appropriate for the current environment.

func (*OCI1IndexPublic) Clone added in v5.25.0 

func (index *OCI1IndexPublic) Clone() ListPublic

Clone returns a deep copy of this list and its contents.

func (*OCI1IndexPublic) ConvertToMIMEType added in v5.25.0 

func (index *OCI1IndexPublic) ConvertToMIMEType(manifestMIMEType string) (ListPublic, error)

ConvertToMIMEType converts the passed-in image index to a manifest list of the specified type.

func (*OCI1IndexPublic) Instance added in v5.25.0 

func (index *OCI1IndexPublic) Instance(instanceDigest digest.Digest) (ListUpdate, error)

Instance returns the ListUpdate of a particular instance in the index.

func (*OCI1IndexPublic) Instances added in v5.25.0 

func (index *OCI1IndexPublic) Instances() []digest.Digest

Instances returns a slice of digests of the manifests that this index knows of.

func (*OCI1IndexPublic) MIMEType added in v5.25.0 

func (index *OCI1IndexPublic) MIMEType() string

MIMEType returns the MIME type of this particular manifest index.

func (*OCI1IndexPublic) Serialize added in v5.25.0 

func (index *OCI1IndexPublic) Serialize() ([]byte, error)

Serialize returns the index in a blob format. NOTE: Serialize() does not in general reproduce the original blob if this object was loaded from one, even if no modifications were made!

func (*OCI1IndexPublic) ToOCI1Index added in v5.25.0 

func (index *OCI1IndexPublic) ToOCI1Index() (*OCI1IndexPublic, error)

ToOCI1Index returns the index encoded as an OCI1 index.

func (*OCI1IndexPublic) ToSchema2List added in v5.25.0 

func (index *OCI1IndexPublic) ToSchema2List() (*Schema2ListPublic, error)

ToSchema2List returns the index encoded as a Schema2 list.

func (*OCI1IndexPublic) UpdateInstances added in v5.25.0 

func (index *OCI1IndexPublic) UpdateInstances(updates []ListUpdate) error

UpdateInstances updates the sizes, digests, and media types of the manifests which the list catalogs.

type ReuseConditions added in v5.31.0 

type ReuseConditions struct {
	PossibleManifestFormats []string                    // If set, a set of possible manifest formats; at least one should support the reused layer
	RequiredCompression     *compressiontypes.Algorithm // If set, only reuse layers with a matching algorithm
}

ReuseConditions are an input to CandidateCompressionMatchesReuseConditions; it is a struct to allow longer and better-documented field names.

type Schema2Descriptor added in v5.25.0 

type Schema2Descriptor struct {
	MediaType string        `json:"mediaType"`
	Size      int64         `json:"size"`
	Digest    digest.Digest `json:"digest"`
	URLs      []string      `json:"urls,omitempty"`
}

Schema2Descriptor is a “descriptor” in docker/distribution schema 2.

This is publicly visible as c/image/manifest.Schema2Descriptor.

type Schema2List added in v5.25.0 

type Schema2List struct {
	Schema2ListPublic
}

Schema2List is a list of platform-specific manifests.

func Schema2ListFromManifest added in v5.25.0 

func Schema2ListFromManifest(manifest []byte) (*Schema2List, error)

Schema2ListFromManifest creates a Schema2 manifest list instance from marshalled JSON, presumably generated by encoding a Schema2 manifest list.

func (*Schema2List) Clone added in v5.25.0 

func (index *Schema2List) Clone() ListPublic

func (*Schema2List) CloneInternal added in v5.25.0 

func (index *Schema2List) CloneInternal() List

func (*Schema2List) EditInstances added in v5.26.0 

func (index *Schema2List) EditInstances(editInstances []ListEdit) error

type Schema2ListPublic added in v5.25.0 

type Schema2ListPublic struct {
	SchemaVersion int                         `json:"schemaVersion"`
	MediaType     string                      `json:"mediaType"`
	Manifests     []Schema2ManifestDescriptor `json:"manifests"`
}

Schema2ListPublic is a list of platform-specific manifests. This is publicly visible as c/image/manifest.Schema2List. Internal users should usually use Schema2List instead.

func Schema2ListPublicClone added in v5.25.0 

func Schema2ListPublicClone(list *Schema2ListPublic) *Schema2ListPublic

Schema2ListPublicClone creates a deep copy of the passed-in list. This is publicly visible as c/image/manifest.Schema2ListClone.

func Schema2ListPublicFromComponents added in v5.25.0 

func Schema2ListPublicFromComponents(components []Schema2ManifestDescriptor) *Schema2ListPublic

Schema2ListPublicFromComponents creates a Schema2 manifest list instance from the supplied data. This is publicly visible as c/image/manifest.Schema2ListFromComponents.

func Schema2ListPublicFromManifest added in v5.25.0 

func Schema2ListPublicFromManifest(manifest []byte) (*Schema2ListPublic, error)

Schema2ListPublicFromManifest creates a Schema2 manifest list instance from marshalled JSON, presumably generated by encoding a Schema2 manifest list. This is publicly visible as c/image/manifest.Schema2ListFromManifest.

func (*Schema2ListPublic) ChooseInstance added in v5.25.0 

func (list *Schema2ListPublic) ChooseInstance(ctx *types.SystemContext) (digest.Digest, error)

ChooseInstance parses blob as a schema2 manifest list, and returns the digest of the image which is appropriate for the current environment.

func (*Schema2ListPublic) ChooseInstanceByCompression added in v5.25.0 

func (list *Schema2ListPublic) ChooseInstanceByCompression(ctx *types.SystemContext, preferGzip types.OptionalBool) (digest.Digest, error)

func (*Schema2ListPublic) Clone added in v5.25.0 

func (list *Schema2ListPublic) Clone() ListPublic

Clone returns a deep copy of this list and its contents.

func (*Schema2ListPublic) ConvertToMIMEType added in v5.25.0 

func (list *Schema2ListPublic) ConvertToMIMEType(manifestMIMEType string) (ListPublic, error)

ConvertToMIMEType converts the passed-in manifest list to a manifest list of the specified type.

func (*Schema2ListPublic) Instance added in v5.25.0 

func (list *Schema2ListPublic) Instance(instanceDigest digest.Digest) (ListUpdate, error)

Instance returns the ListUpdate of a particular instance in the list.

func (*Schema2ListPublic) Instances added in v5.25.0 

func (list *Schema2ListPublic) Instances() []digest.Digest

Instances returns a slice of digests of the manifests that this list knows of.

func (*Schema2ListPublic) MIMEType added in v5.25.0 

func (list *Schema2ListPublic) MIMEType() string

MIMEType returns the MIME type of this particular manifest list.

func (*Schema2ListPublic) Serialize added in v5.25.0 

func (list *Schema2ListPublic) Serialize() ([]byte, error)

Serialize returns the list in a blob format. NOTE: Serialize() does not in general reproduce the original blob if this object was loaded from one, even if no modifications were made!

func (*Schema2ListPublic) ToOCI1Index added in v5.25.0 

func (list *Schema2ListPublic) ToOCI1Index() (*OCI1IndexPublic, error)

ToOCI1Index returns the list encoded as an OCI1 index.

func (*Schema2ListPublic) ToSchema2List added in v5.25.0 

func (list *Schema2ListPublic) ToSchema2List() (*Schema2ListPublic, error)

ToSchema2List returns the list encoded as a Schema2 list.

func (*Schema2ListPublic) UpdateInstances added in v5.25.0 

func (index *Schema2ListPublic) UpdateInstances(updates []ListUpdate) error

UpdateInstances updates the sizes, digests, and media types of the manifests which the list catalogs.

type Schema2ManifestDescriptor added in v5.25.0 

type Schema2ManifestDescriptor struct {
	Schema2Descriptor
	Platform Schema2PlatformSpec `json:"platform"`
}

Schema2ManifestDescriptor references a platform-specific manifest. This is publicly visible as c/image/manifest.Schema2ManifestDescriptor.

type Schema2PlatformSpec added in v5.25.0 

type Schema2PlatformSpec struct {
	Architecture string   `json:"architecture"`
	OS           string   `json:"os"`
	OSVersion    string   `json:"os.version,omitempty"`
	OSFeatures   []string `json:"os.features,omitempty"`
	Variant      string   `json:"variant,omitempty"`
	Features     []string `json:"features,omitempty"` // removed in OCI
}

Schema2PlatformSpec describes the platform which a particular manifest is specialized for. This is publicly visible as c/image/manifest.Schema2PlatformSpec.

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.