Documentation
¶
Overview ¶
Package docker is the storage layout of Docker and OCI images in a repository's item tree (decision 0031), which the JFrog CLI reads with AQL and the storage API: an image is a folder, each tag a folder of its own below it and each manifest pushed by digest a folder named sha256:<hex>, and every blob a file named sha256__<hex> in the folders of the images that use it. Finished uploads wait in the image's _uploads folder until a manifest links them. A format package never imports internal/server, nor the item service, which calls the format hooks.
Index ¶
- Constants
- Variables
- func BlobFile(hex string) string
- func Compare(a, b string) int
- func DigestFolder(hex string) string
- func FindBlob(ctx context.Context, items store.ItemStore, repoKey, name, hex string) (types.Item, error)
- func FindManifest(ctx context.Context, items store.ItemStore, repoKey, name, hex string) (types.Item, error)
- func FindReferrers(ctx context.Context, items store.ItemStore, ...) ([]aql.Hit, error)
- func FolderManifest(ctx context.Context, items store.ItemStore, repoKey string, cached bool, ...) (types.Item, bool, error)
- func ImageManifests(ctx context.Context, items store.ItemStore, repoKey, name string) ([]aql.Hit, error)
- func IsDigestFolder(folder string) bool
- func ManifestFolders(ctx context.Context, items store.ItemStore, repoKey, name, hex string) ([]string, error)
- func Manifests(ctx context.Context, items store.ItemStore, repoKey, name string) ([]types.Item, error)
- func Properties(m Manifest, name, folder string, c Config) types.Properties
- func PushTime(m types.Item) time.Time
- func ReservedTag(tag string) bool
- func Retained(ctx context.Context, items store.ItemStore, repoKey, name, tag string) ([]types.Item, error)
- func SHA256Hex(d string) (hex string, ok bool)
- func Serves(t repo.PackageType) bool
- func Tags(ctx context.Context, items store.ItemStore, repoKey, name string) ([]string, bool, error)
- func UploadPath(name, hex string) string
- func ValidDigest(d string) bool
- func ValidTag(tag string) bool
- type Config
- type Descriptor
- type Handler
- func (Handler) Classify(_ repo.Config, p string) format.Class
- func (Handler) Deleted(ctx context.Context, env format.Env, c repo.Config, removed []types.Item) error
- func (Handler) Deleting(context.Context, format.Env, repo.Config, types.Item) error
- func (Handler) Deployed(ctx context.Context, env format.Env, c repo.Config, it types.Item) error
- func (Handler) Reindex(ctx context.Context, env format.Env, c repo.Config) error
- type Image
- type Manifest
- type Platform
Constants ¶
const ( MediaTypeOCIManifest = "application/vnd.oci.image.manifest.v1+json" MediaTypeOCIIndex = "application/vnd.oci.image.index.v1+json" MediaTypeDockerManifest = "application/vnd.docker.distribution.manifest.v2+json" MediaTypeDockerList = "application/vnd.docker.distribution.manifest.list.v2+json" )
The manifest media types the registry stores (decision 0031).
const ( ManifestFile = "manifest.json" ListManifestFile = "list.manifest.json" )
The stored manifest's file name in its tag or digest folder, which jf reads (research 23, 5.1).
const ( ManifestProperty = "docker.manifest" ManifestDigestProperty = "docker.manifest.digest" ManifestTypeProperty = "docker.manifest.type" RepoNameProperty = "docker.repoName" SHA256Property = "sha256" // LabelPropertyPrefix starts the property of each label of an image's // config. LabelPropertyPrefix = "docker.label." // OSProperty and ArchitectureProperty are an image's platform, from its // config, as Artifactory sets them on manifest.json from 7.125.4. OSProperty = "docker.os" ArchitectureProperty = "docker.architecture" )
The properties set on every stored manifest (decision 0031). jf finds a manifest by digest through ManifestDigestProperty and SHA256Property, and Docker clients pulling through Artifactory fail with "missing signature key" when one is wrong (research 23, 5.2).
const ( // SubjectProperty is the subject's digest. SubjectProperty = "oci.subject" // ArtifactTypeProperty is the type the referrers API reports and filters // the manifest by. ArtifactTypeProperty = "oci.artifactType" )
The properties a manifest with a subject carries, from which the referrers API is answered: no referrers.json is written (DV-036).
const MaxManifestSize = 4 << 20
MaxManifestSize is the largest manifest accepted: the specification asks registries to take at least 4 MB, and a larger one answers 413.
const UploadsFolder = "_uploads"
UploadsFolder is the folder below an image that holds its finished uploads, as on Artifactory; jf leaves it out of its searches.
Variables ¶
var ErrManifestInvalid = errors.New("docker: invalid manifest")
ErrManifestInvalid is a manifest the registry refuses to store: MANIFEST_INVALID.
Functions ¶
func Compare ¶
Compare orders tags and image names as the specification orders tags, case-insensitively, with names that differ only in case ordered by their bytes, so that the order is total and a page continued after last neither repeats nor skips a name (decision 0031).
func DigestFolder ¶
DigestFolder is the folder below an image of the manifest pushed by its digest, whose SHA-256 is hex: every platform manifest of a multi-architecture push, and a tag's previous manifest kept by Tag Retention.
func FindBlob ¶
func FindBlob( ctx context.Context, items store.ItemStore, repoKey, name, hex string, ) (types.Item, error)
FindBlob returns a file holding the blob hex in one of the image name's own folders: a tag folder, a digest folder or _uploads, each a direct child of name (decision 0031). A blob only in a deeper folder belongs to another image whose name begins with this one, and is not found: the depth puts the file exactly two levels below name. store.ErrNotFound when there is none.
func FindManifest ¶
func FindManifest( ctx context.Context, items store.ItemStore, repoKey, name, hex string, ) (types.Item, error)
FindManifest returns the stored manifest whose SHA-256 is hex in one of the image name's own folders, a tag folder or a digest folder, each a direct child of name, as FindBlob finds blobs. store.ErrNotFound when there is none.
func FindReferrers ¶
func FindReferrers( ctx context.Context, items store.ItemStore, repoKey, name, subject, artifactType string, ) ([]aql.Hit, error)
FindReferrers returns the stored manifests in the image name's own folders whose subject is the digest subject, those of artifactType alone when it is set, each with its properties. A manifest stored in several folders, by digest and by tag, is a hit in each.
func FolderManifest ¶
func FolderManifest( ctx context.Context, items store.ItemStore, repoKey string, cached bool, dir string, ) (types.Item, bool, error)
FolderManifest returns the manifest file in the image folder dir; ok is false when the folder holds none, and so is no tag.
func ImageManifests ¶
func ImageManifests( ctx context.Context, items store.ItemStore, repoKey, name string, ) ([]aql.Hit, error)
ImageManifests returns every stored manifest, image or index, in the image name's own folders: its tag folders and its digest folders, each a direct child of name, as FindManifest searches them. A manifest of an image whose name begins with this one sits deeper and is left out. Each hit carries its properties.
func IsDigestFolder ¶
IsDigestFolder reports whether a folder below an image is a digest folder (a push by digest, a platform manifest or a retained version), which is never a tag.
func ManifestFolders ¶
func ManifestFolders( ctx context.Context, items store.ItemStore, repoKey, name, hex string, ) ([]string, error)
ManifestFolders returns the folders of the image name in repoKey that hold the manifest whose SHA-256 is hex, tag folders and the digest folder alike, in the specification's order.
func Manifests ¶
func Manifests( ctx context.Context, items store.ItemStore, repoKey, name string, ) ([]types.Item, error)
Manifests returns every manifest stored in the image name, in its tag and digest folders alike.
func Properties ¶
func Properties(m Manifest, name, folder string, c Config) types.Properties
Properties are the properties of the manifest stored in folder of the image name: the five jf and Docker clients rely on, oci.subject and oci.artifactType for a manifest with a subject, which the referrers API is answered from (DV-036), the image's docker.os and docker.architecture, and a docker.label.<label> for each of its labels. A label whose name no property key may carry is left out.
func PushTime ¶
PushTime is when a stored manifest was last written, its tag's place in the order of decision 0018: a later push of a different manifest replaces the file and so moves the tag to the newest place. A move keeps the time; a copy is a push at its target.
func ReservedTag ¶
ReservedTag reports whether a valid tag would collide with a folder the layout keeps beside tag folders: _uploads, as on Artifactory. A digest folder needs no reservation, since no tag may hold its colon, and sha256__<hex> is an ordinary tag, as in a 7.x local repository (research 23, 8).
func Retained ¶
func Retained( ctx context.Context, items store.ItemStore, repoKey, name, tag string, ) ([]types.Item, error)
Retained returns the previous manifests of the image name's tag that Tag Retention kept (decision 0031), oldest push first. A retained manifest is one that moved from the tag folder to its own digest folder and so still names the tag in docker.manifest, where a manifest pushed by digest names its digest folder.
func SHA256Hex ¶
SHA256Hex returns the hex of a valid sha256 digest; ok is false for another algorithm or an invalid digest.
func Serves ¶
func Serves(t repo.PackageType) bool
Serves reports whether repositories of package type t hold images: docker, and the oci and helmoci types that share its protocol and layout (research 04).
func Tags ¶
func Tags( ctx context.Context, items store.ItemStore, repoKey, name string, ) ([]string, bool, error)
Tags returns the tags of the image name in repoKey in the specification's order: the folders directly below it that hold a manifest (decision 0031). A digest folder holds a manifest but is no tag, and a reserved name is never one. found is false when the image holds no manifest at all, which the registry answers NAME_UNKNOWN.
func UploadPath ¶
UploadPath is the path of the finished upload of hex in the image name.
func ValidDigest ¶
ValidDigest reports whether d is a digest by the specification's grammar; a sha256 digest must also be 64 lower-case hex characters.
Types ¶
type Config ¶
type Config struct {
// OS and Architecture are the config's own fields. A platform variant
// (arm's v7, arm64's v8) is not part of either: Artifactory documents
// no variant property, so docker.architecture holds the config's
// architecture exactly as an index's platform names it, recorded as
// [I] on #216 (decision 0031).
OS string
Architecture string
Labels map[string]string
}
Config is what an image's config gives its manifest's properties.
type Descriptor ¶
type Descriptor struct {
MediaType string `json:"mediaType"`
Digest string `json:"digest"`
Size int64 `json:"size"`
ArtifactType string `json:"artifactType,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
// Platform is the platform an index's entry names; nil when it names
// none, as on every descriptor outside an index.
Platform *Platform `json:"platform,omitempty"`
}
Descriptor points at a blob or a manifest from a manifest.
type Handler ¶
type Handler struct {
// The generic format admits writes under every package type's deploy
// policy.
generic.Handler
}
Handler is the format of docker, oci and helmoci repositories, which the item service calls on every write and delete in them. It keeps the package index of decision 0018: an image is a package while it holds any manifest, tagged or not, and each tag folder holding a manifest is a version whose files are the folder's items, ordered by the tag's last push. Digest folders and _uploads are no versions.
func (Handler) Classify ¶
Classify reports a tag folder's manifests as metadata, since a push moves the tag to other content under the same path, and every other file, digest-addressed or a layer, as unique.
func (Handler) Deleted ¶
func (Handler) Deleted( ctx context.Context, env format.Env, c repo.Config, removed []types.Item, ) error
Deleted brings the index back in line with the tree after files of images were removed: a tag folder left without a manifest is no longer a version even if blobs remain in it, and an image is a package exactly while it still holds a manifest somewhere, which the item service's pruning of empty versions cannot know.
func (Handler) Deleting ¶
Deleting runs before a file of an image is removed. The item service drops the file's version link with it; Deleted settles the rest.
func (Handler) Deployed ¶
Deployed indexes a file stored in an image. A manifest in a tag folder makes the folder a version and links every file already in it, which covers copies, moves and restores that land the manifest after its blobs; another file joins its folder's version once the folder is a tag. A manifest in a digest folder keeps its image a package.
type Image ¶
Image is an image in a repository.
type Manifest ¶
type Manifest struct {
// MediaType is the type the manifest is stored as: the Content-Type it
// was pushed with.
MediaType string
// Digest is the SHA-256 of the exact bytes pushed, in hex.
Digest string
// Config and Layers are an image manifest's blobs.
Config *Descriptor
Layers []Descriptor
// Manifests are an index's children.
Manifests []Descriptor
// Subject is the manifest this one refers to, if any.
Subject *Descriptor
// ArtifactType and Annotations are the manifest's own, which the
// referrers API reports for it.
ArtifactType string
Annotations map[string]string
}
Manifest is a parsed image manifest, image index or Docker manifest list.
func ParseManifest ¶
ParseManifest parses body, pushed with contentType, as the manifest whose SHA-256 is hex. It refuses with ErrManifestInvalid a schema-1 manifest (DV-034), any type but the four stored, a body that does not parse, a mediaType field that disagrees with contentType, and descriptors without a valid digest. Without a Content-Type the body's own mediaType names the type.
func (Manifest) BlobDescriptors ¶
func (m Manifest) BlobDescriptors() []Descriptor
BlobDescriptors are the descriptors behind Blobs: the config and every layer the registry must hold, in order and with any repeats, so that each descriptor's size can be checked against the stored content.
func (Manifest) Blobs ¶
Blobs are the digests of the blobs that must be in the image before an image manifest is stored: its config and its layers, once each, in the manifest's order. Non-distributable and foreign layers live elsewhere by design and are not required (decision 0031).
func (Manifest) Children ¶
Children are the digests of an index's manifests, once each, in the index's order.
func (Manifest) ConfigType ¶
ConfigType is the media type of an image manifest's config, "" for an index.
func (Manifest) ReferrerType ¶
ReferrerType is the artifactType the referrers API reports for the manifest: its own artifactType, or for an image manifest without one its config's media type, as the specification says. An index without one has none.