Help us shape the future of Go! Take the 2026 Go Developer Survey

docker

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 20 Imported by: 0

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

View Source
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).

View Source
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).

View Source
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).

View Source
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).

View Source
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.

View Source
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

View Source
var ErrManifestInvalid = errors.New("docker: invalid manifest")

ErrManifestInvalid is a manifest the registry refuses to store: MANIFEST_INVALID.

Functions

func BlobFile

func BlobFile(hex string) string

BlobFile is the file name of the blob whose SHA-256 is hex.

func Compare

func Compare(a, b string) int

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

func DigestFolder(hex string) string

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

func IsDigestFolder(folder string) bool

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

func PushTime(m types.Item) time.Time

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

func ReservedTag(tag string) bool

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

func SHA256Hex(d string) (hex string, ok bool)

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

func UploadPath(name, hex string) string

UploadPath is the path of the finished upload of hex in the image name.

func ValidDigest

func ValidDigest(d string) bool

ValidDigest reports whether d is a digest by the specification's grammar; a sha256 digest must also be 64 lower-case hex characters.

func ValidTag

func ValidTag(tag string) bool

ValidTag reports whether tag is a tag by the specification's grammar.

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.

func ReadConfig

func ReadConfig(configType string, r io.Reader) Config

ReadConfig reads an image config of media type configType from r. A config of another type, an artifact's, or one too large or malformed to read gives nothing: this is metadata, and a push never fails for it.

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

func (Handler) Classify(_ repo.Config, p string) format.Class

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

func (Handler) Deployed(ctx context.Context, env format.Env, c repo.Config, it types.Item) error

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.

func (Handler) Reindex

func (Handler) Reindex(ctx context.Context, env format.Env, c repo.Config) error

Reindex rebuilds the image index of the repository from its tree, in one transaction.

type Image

type Image struct {
	Repo string
	Name string
}

Image is an image in a repository.

func Images

func Images(ctx context.Context, items store.ItemStore, keys []string) ([]Image, error)

Images returns the images of the repositories keys, each a folder holding at least one manifest in a tag or digest folder of its own (decision 0031), ordered by repository and then as tags are ordered. Whether a name is valid is the caller's to judge.

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

func ParseManifest(contentType string, body []byte, hex string) (Manifest, error)

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

func (m Manifest) Blobs() []string

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

func (m Manifest) Children() []string

Children are the digests of an index's manifests, once each, in the index's order.

func (Manifest) ConfigType

func (m Manifest) ConfigType() string

ConfigType is the media type of an image manifest's config, "" for an index.

func (Manifest) File

func (m Manifest) File() string

File is the name the manifest is stored under in its folder.

func (Manifest) Index

func (m Manifest) Index() bool

Index reports whether the manifest is an image index or manifest list.

func (Manifest) ReferrerType

func (m Manifest) ReferrerType() string

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.

type Platform

type Platform struct {
	OS           string `json:"os"`
	Architecture string `json:"architecture"`
	Variant      string `json:"variant,omitempty"`
}

Platform is the platform an index's entry runs on. buildx names an attestation manifest's platform unknown/unknown.

Jump to

Keyboard shortcuts

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