From 6d9822af08a20c788e156aa09b0a0ac9aa4a89da Mon Sep 17 00:00:00 2001 From: Brandon Mitchell Date: Sat, 30 Sep 2023 09:05:53 -0400 Subject: [PATCH] Cleanup links in "deprecated" comments Signed-off-by: Brandon Mitchell --- mod/config.go | 22 ++++----- mod/layer.go | 22 ++++----- mod/manifest.go | 15 +++--- mod/mod.go | 4 +- regclient.go | 14 +++--- scheme/scheme.go | 96 +++++++++++++++++++------------------- types/blob/common.go | 6 +-- types/manifest/docker1.go | 4 +- types/manifest/manifest.go | 56 +++++++++++++--------- types/mediatype.go | 40 ++++++++-------- 10 files changed, 145 insertions(+), 134 deletions(-) diff --git a/mod/config.go b/mod/config.go index 6fe6e59..5a27b53 100644 --- a/mod/config.go +++ b/mod/config.go @@ -15,7 +15,7 @@ import ( "github.com/regclient/regclient/types/ref" ) -// WithBuildArgRm removes a build arg from the config history +// WithBuildArgRm removes a build arg from the config history. func WithBuildArgRm(arg string, value *regexp.Regexp) Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsOCIConfig = append(dc.stepsOCIConfig, func(ctx context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, doc *dagOCIConfig) error { @@ -54,7 +54,7 @@ func WithBuildArgRm(arg string, value *regexp.Regexp) Opts { } } -// WithConfigTimestamp sets the timestamp on the config entries based on options +// WithConfigTimestamp sets the timestamp on the config entries based on options. func WithConfigTimestamp(optTime OptTime) Opts { return func(dc *dagConfig, dm *dagManifest) error { if optTime.Set.IsZero() && optTime.FromLabel == "" { @@ -161,9 +161,9 @@ func WithConfigTimestamp(optTime OptTime) Opts { } } -// WithConfigTimestampFromLabel sets the max timestamp in the config to match a label value +// WithConfigTimestampFromLabel sets the max timestamp in the config to match a label value. // -// Deprecated: replace with WithConfigTimestamp +// Deprecated: replace with [WithConfigTimestamp]. func WithConfigTimestampFromLabel(label string) Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsOCIConfig = append(dc.stepsOCIConfig, func(c context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, doc *dagOCIConfig) error { @@ -202,9 +202,9 @@ func WithConfigTimestampFromLabel(label string) Opts { } } -// WithConfigTimestampMax sets the max timestamp on any config objects +// WithConfigTimestampMax sets the max timestamp on any config objects. // -// Deprecated: replace with WithConfigTimestamp +// Deprecated: replace with [WithConfigTimestamp]. func WithConfigTimestampMax(t time.Time) Opts { return WithConfigTimestamp(OptTime{ Set: t, @@ -212,7 +212,7 @@ func WithConfigTimestampMax(t time.Time) Opts { }) } -// WithExposeAdd defines an exposed port in the image config +// WithExposeAdd defines an exposed port in the image config. func WithExposeAdd(port string) Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsOCIConfig = append(dc.stepsOCIConfig, func(ctx context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, doc *dagOCIConfig) error { @@ -236,7 +236,7 @@ func WithExposeAdd(port string) Opts { } } -// WithExposeRm deletes an exposed from the image config +// WithExposeRm deletes an exposed from the image config. func WithExposeRm(port string) Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsOCIConfig = append(dc.stepsOCIConfig, func(ctx context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, doc *dagOCIConfig) error { @@ -260,7 +260,7 @@ func WithExposeRm(port string) Opts { } } -// WithLabel sets or deletes a label from the image config +// WithLabel sets or deletes a label from the image config. func WithLabel(name, value string) Opts { return func(dc *dagConfig, dm *dagManifest) error { // extract the list for platforms to update from the name @@ -321,7 +321,7 @@ func WithLabel(name, value string) Opts { } } -// WithVolumeAdd defines a volume in the image config +// WithVolumeAdd defines a volume in the image config. func WithVolumeAdd(volume string) Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsOCIConfig = append(dc.stepsOCIConfig, func(ctx context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, doc *dagOCIConfig) error { @@ -345,7 +345,7 @@ func WithVolumeAdd(volume string) Opts { } } -// WithVolumeRm deletes a volume from the image config +// WithVolumeRm deletes a volume from the image config. func WithVolumeRm(volume string) Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsOCIConfig = append(dc.stepsOCIConfig, func(ctx context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, doc *dagOCIConfig) error { diff --git a/mod/layer.go b/mod/layer.go index a32864c..689c684 100644 --- a/mod/layer.go +++ b/mod/layer.go @@ -42,7 +42,7 @@ func WithLayerReproducible() Opts { } // WithLayerRmCreatedBy deletes a layer based on a regex of the created by field -// in the config history for that layer +// in the config history for that layer. func WithLayerRmCreatedBy(re regexp.Regexp) Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsManifest = append(dc.stepsManifest, func(c context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, dm *dagManifest) error { @@ -125,7 +125,7 @@ func WithLayerRmIndex(index int) Opts { } } -// WithLayerStripFile removes a file from within the layer tar +// WithLayerStripFile removes a file from within the layer tar. func WithLayerStripFile(file string) Opts { file = strings.Trim(file, "/") fileRE := regexp.MustCompile("^/?" + regexp.QuoteMeta(file) + "(/.*)?$") @@ -140,7 +140,7 @@ func WithLayerStripFile(file string) Opts { } } -// WithLayerTimestamp sets the timestamp on files in the layers based on options +// WithLayerTimestamp sets the timestamp on files in the layers based on options. func WithLayerTimestamp(optTime OptTime) Opts { return func(dc *dagConfig, dm *dagManifest) error { if optTime.Set.IsZero() && optTime.FromLabel == "" { @@ -275,9 +275,9 @@ func layerGetBaseRef(c context.Context, rc *regclient.RegClient, r ref.Ref, m ma return dl, nil } -// WithLayerTimestampFromLabel sets the max layer timestamp based on a label in the image +// WithLayerTimestampFromLabel sets the max layer timestamp based on a label in the image. // -// Deprecated: replace with WithLayerTimestamp +// Deprecated: replace with [WithLayerTimestamp]. func WithLayerTimestampFromLabel(label string) Opts { t := time.Time{} return func(dc *dagConfig, dm *dagManifest) error { @@ -329,9 +329,9 @@ func WithLayerTimestampFromLabel(label string) Opts { } } -// WithLayerTimestampMax ensures no file timestamps are after specified time +// WithLayerTimestampMax ensures no file timestamps are after specified time. // -// Deprecated: replace with WithLayerTimestamp +// Deprecated: replace with [WithLayerTimestamp]. func WithLayerTimestampMax(t time.Time) Opts { return WithLayerTimestamp(OptTime{ Set: t, @@ -339,7 +339,7 @@ func WithLayerTimestampMax(t time.Time) Opts { }) } -// WithFileTarTime processes a tar file within a layer and adjusts the timestamps according to optTime +// WithFileTarTime processes a tar file within a layer and adjusts the timestamps according to optTime. func WithFileTarTime(name string, optTime OptTime) Opts { name = strings.TrimPrefix(name, "/") return func(dc *dagConfig, dm *dagManifest) error { @@ -480,9 +480,9 @@ func WithFileTarTime(name string, optTime OptTime) Opts { } } -// WithFileTarTimeMax processes a tar file within a layer and rewrites the contents with a max timestamp +// WithFileTarTimeMax processes a tar file within a layer and rewrites the contents with a max timestamp. // -// Deprecated: replace with WithFileTarTime +// Deprecated: replace with [WithFileTarTime]. func WithFileTarTimeMax(name string, t time.Time) Opts { return WithFileTarTime(name, OptTime{ Set: t, @@ -496,7 +496,7 @@ type tmpReader struct { filename string } -// Read for tmpReader passes through the read and deletes the tmp file when the read completes +// Read for tmpReader passes through the read and deletes the tmp file when the read completes. func (t *tmpReader) Read(p []byte) (int, error) { if t.file == nil { return 0, io.EOF diff --git a/mod/manifest.go b/mod/manifest.go index ca5a7a9..35a686c 100644 --- a/mod/manifest.go +++ b/mod/manifest.go @@ -91,7 +91,7 @@ func WithAnnotation(name, value string) Opts { } } -// WithAnnotationOCIBase adds annotations for the base image +// WithAnnotationOCIBase adds annotations for the base image. func WithAnnotationOCIBase(rBase ref.Ref, dBase digest.Digest) Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsManifest = append(dc.stepsManifest, func(ctx context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, dm *dagManifest) error { @@ -157,7 +157,7 @@ func WithAnnotationOCIBase(rBase ref.Ref, dBase digest.Digest) Opts { } } -// WithLabelToAnnotation copies image config labels to manifest annotations +// WithLabelToAnnotation copies image config labels to manifest annotations. func WithLabelToAnnotation() Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsManifest = append(dc.stepsManifest, func(c context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, dm *dagManifest) error { @@ -209,7 +209,7 @@ func WithLabelToAnnotation() Opts { } } -// WithManifestToDocker converts the manifest to Docker schema2 media types +// WithManifestToDocker converts the manifest to Docker schema2 media types. func WithManifestToDocker() Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsManifest = append(dc.stepsManifest, func(c context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, dm *dagManifest) error { @@ -281,7 +281,7 @@ func WithManifestToDocker() Opts { } } -// WithManifestToOCI converts the manifest to OCI media types +// WithManifestToOCI converts the manifest to OCI media types. func WithManifestToOCI() Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsManifest = append(dc.stepsManifest, func(c context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, dm *dagManifest) error { @@ -345,7 +345,7 @@ const ( dockerReferenceDigest = "vnd.docker.reference.digest" ) -// WithManifestToOCIReferrers converts other referrer types to OCI subject/referrers +// WithManifestToOCIReferrers converts other referrer types to OCI subject/referrers. func WithManifestToOCIReferrers() Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsManifest = append(dc.stepsManifest, func(c context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, dm *dagManifest) error { @@ -422,7 +422,7 @@ func WithManifestToOCIReferrers() Opts { } } -// WithExternalURLsRm strips external URLs from descriptors and adjusts media type to match +// WithExternalURLsRm strips external URLs from descriptors and adjusts media type to match. func WithExternalURLsRm() Opts { return func(dc *dagConfig, dm *dagManifest) error { dc.stepsManifest = append(dc.stepsManifest, func(ctx context.Context, rc *regclient.RegClient, rSrc, rTgt ref.Ref, dm *dagManifest) error { @@ -489,6 +489,7 @@ func WithExternalURLsRm() Opts { } } +// WithRebase attempts to rebase the image using OCI annotations identifying the base image. func WithRebase() Opts { return func(dc *dagConfig, dm *dagManifest) error { ma, ok := dm.m.(manifest.Annotator) @@ -522,7 +523,7 @@ func WithRebase() Opts { } } -// WithRebaseRefs swaps the base image layers from the old to the new reference +// WithRebaseRefs swaps the base image layers from the old to the new reference. func WithRebaseRefs(rOld, rNew ref.Ref) Opts { // cache old and new manifests, variable is nil until first pulled return func(dc *dagConfig, dm *dagManifest) error { diff --git a/mod/mod.go b/mod/mod.go index 69d89c9..21b4a0a 100644 --- a/mod/mod.go +++ b/mod/mod.go @@ -20,7 +20,7 @@ import ( // Opts defines options for Apply type Opts func(*dagConfig, *dagManifest) error -// OptTime defines time settings for WithConfigTimestamp and WithLayerTimestamp +// OptTime defines time settings for [WithConfigTimestamp] and [WithLayerTimestamp]. type OptTime struct { Set time.Time // time to set, this or FromLabel are required FromLabel string // label from which to extract set time @@ -43,7 +43,7 @@ var ( } ) -// Apply applies a set of modifications to an image (manifest, configs, and layers) +// Apply applies a set of modifications to an image (manifest, configs, and layers). func Apply(ctx context.Context, rc *regclient.RegClient, rSrc ref.Ref, opts ...Opts) (ref.Ref, error) { // check for the various types of mods (manifest, config, layer) // some may span like copying layers from config to manifest diff --git a/regclient.go b/regclient.go index b8c52ef..c59995b 100644 --- a/regclient.go +++ b/regclient.go @@ -40,7 +40,7 @@ type RegClient struct { fs rwfs.RWFS } -// Opt functions are used to configure NewRegClient. +// Opt functions are used by [New] to create a [*RegClient]. type Opt func(*RegClient) // New returns a registry client. @@ -97,7 +97,7 @@ func New(opts ...Opt) *RegClient { // WithBlobLimit sets the max size for chunked blob uploads which get stored in memory. // -// Deprecated: replace with WithRegOpts(reg.WithBlobLimit(limit)). +// Deprecated: replace with WithRegOpts(reg.WithBlobLimit(limit)), see [WithRegOpts] and [reg.WithBlobLimit]. func WithBlobLimit(limit int64) Opt { return func(rc *RegClient) { rc.regOpts = append(rc.regOpts, reg.WithBlobLimit(limit)) @@ -106,7 +106,7 @@ func WithBlobLimit(limit int64) Opt { // WithBlobSize overrides default blob sizes. // -// Deprecated: replace with WithRegOpts(reg.WithBlobSize(chunk, max)). +// Deprecated: replace with WithRegOpts(reg.WithBlobSize(chunk, max)), see [WithRegOpts] and [reg.WithBlobSize]. func WithBlobSize(chunk, max int64) Opt { return func(rc *RegClient) { rc.regOpts = append(rc.regOpts, reg.WithBlobSize(chunk, max)) @@ -115,7 +115,7 @@ func WithBlobSize(chunk, max int64) Opt { // WithCertDir adds a path of certificates to trust similar to Docker's /etc/docker/certs.d. // -// Deprecated: replace with WithRegOpts(reg.WithCertDirs(path)). +// Deprecated: replace with WithRegOpts(reg.WithCertDirs(path)), see [WithRegOpts] and [reg.WithCertDirs]. func WithCertDir(path ...string) Opt { return func(rc *RegClient) { rc.regOpts = append(rc.regOpts, reg.WithCertDirs(path)) @@ -131,7 +131,7 @@ func WithConfigHost(configHost ...config.Host) Opt { // WithConfigHosts adds a list of config host settings. // -// Deprecated: replace with WithConfigHost. +// Deprecated: replace with [WithConfigHost]. func WithConfigHosts(configHosts []config.Host) Opt { return WithConfigHost(configHosts...) } @@ -182,7 +182,7 @@ func WithRegOpts(opts ...reg.Opts) Opt { // WithRetryDelay specifies the time permitted for retry delays. // -// Deprecated: replace with WithRegOpts(reg.WithDelay(delayInit, delayMax)). +// Deprecated: replace with WithRegOpts(reg.WithDelay(delayInit, delayMax)), see [WithRegOpts] and [reg.WithDelay]. func WithRetryDelay(delayInit, delayMax time.Duration) Opt { return func(rc *RegClient) { rc.regOpts = append(rc.regOpts, reg.WithDelay(delayInit, delayMax)) @@ -191,7 +191,7 @@ func WithRetryDelay(delayInit, delayMax time.Duration) Opt { // WithRetryLimit specifies the number of retries for non-fatal errors. // -// Deprecated: replace with WithRegOpts(reg.WithRetryLimit(retryLimit)). +// Deprecated: replace with WithRegOpts(reg.WithRetryLimit(retryLimit)), see [WithRegOpts] and [reg.WithRetryLimit]. func WithRetryLimit(retryLimit int) Opt { return func(rc *RegClient) { rc.regOpts = append(rc.regOpts, reg.WithRetryLimit(retryLimit)) diff --git a/scheme/scheme.go b/scheme/scheme.go index dd1f76c..e4a8616 100644 --- a/scheme/scheme.go +++ b/scheme/scheme.go @@ -1,4 +1,4 @@ -// Package scheme defines the interface for various reference schemes +// Package scheme defines the interface for various reference schemes. package scheme import ( @@ -14,43 +14,43 @@ import ( "github.com/regclient/regclient/types/tag" ) -// API is used to interface between different methods to store images +// API is used to interface between different methods to store images. type API interface { - // BlobDelete removes a blob from the repository + // BlobDelete removes a blob from the repository. BlobDelete(ctx context.Context, r ref.Ref, d types.Descriptor) error - // BlobGet retrieves a blob, returning a reader + // BlobGet retrieves a blob, returning a reader. BlobGet(ctx context.Context, r ref.Ref, d types.Descriptor) (blob.Reader, error) - // BlobHead verifies the existence of a blob, the reader contains the headers but no body to read + // BlobHead verifies the existence of a blob, the reader contains the headers but no body to read. BlobHead(ctx context.Context, r ref.Ref, d types.Descriptor) (blob.Reader, error) - // BlobMount attempts to perform a server side copy of the blob + // BlobMount attempts to perform a server side copy of the blob. BlobMount(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, d types.Descriptor) error - // BlobPut sends a blob to the repository, returns the digest and size when successful + // BlobPut sends a blob to the repository, returns the digest and size when successful. BlobPut(ctx context.Context, r ref.Ref, d types.Descriptor, rdr io.Reader) (types.Descriptor, error) - // ManifestDelete removes a manifest, including all tags that point to that manifest + // ManifestDelete removes a manifest, including all tags that point to that manifest. ManifestDelete(ctx context.Context, r ref.Ref, opts ...ManifestOpts) error - // ManifestGet retrieves a manifest from a repository + // ManifestGet retrieves a manifest from a repository. ManifestGet(ctx context.Context, r ref.Ref) (manifest.Manifest, error) - // ManifestHead gets metadata about the manifest (existence, digest, mediatype, size) + // ManifestHead gets metadata about the manifest (existence, digest, mediatype, size). ManifestHead(ctx context.Context, r ref.Ref) (manifest.Manifest, error) - // ManifestPut sends a manifest to the repository + // ManifestPut sends a manifest to the repository. ManifestPut(ctx context.Context, r ref.Ref, m manifest.Manifest, opts ...ManifestOpts) error - // ReferrerList returns a list of referrers to a given reference + // ReferrerList returns a list of referrers to a given reference. ReferrerList(ctx context.Context, r ref.Ref, opts ...ReferrerOpts) (referrer.ReferrerList, error) - // TagDelete removes a tag from the repository + // TagDelete removes a tag from the repository. TagDelete(ctx context.Context, r ref.Ref) error - // TagList returns a list of tags from the repository + // TagList returns a list of tags from the repository. TagList(ctx context.Context, r ref.Ref, opts ...TagOpts) (*tag.List, error) } -// Closer is used to check if a scheme implements the Close API +// Closer is used to check if a scheme implements the Close API. type Closer interface { Close(ctx context.Context, r ref.Ref) error } -// GCLocker is used to indicate locking is available for GC management +// GCLocker is used to indicate locking is available for GC management. type GCLocker interface { // GCLock a reference to prevent GC from triggering during a put, locks are not exclusive. GCLock(r ref.Ref) @@ -59,81 +59,81 @@ type GCLocker interface { GCUnlock(r ref.Ref) } -// Throttler is used to indicate the scheme implements Throttle +// Throttler is used to indicate the scheme implements Throttle. type Throttler interface { Throttle(r ref.Ref, put bool) []*throttle.Throttle } -// ManifestConfig is used by schemes to import ManifestOpts +// ManifestConfig is used by schemes to import [ManifestOpts]. type ManifestConfig struct { CheckReferrers bool Child bool // used when pushing a child of a manifest list, skips indexing in ocidir Manifest manifest.Manifest } -// ManifestOpts is used to set options on manifest APIs +// ManifestOpts is used to set options on manifest APIs. type ManifestOpts func(*ManifestConfig) -// WithManifestCheckReferrers is used when deleting a manifest -// It indicates the manifest should be fetched and referrers should be deleted if defined +// WithManifestCheckReferrers is used when deleting a manifest. +// It indicates the manifest should be fetched and referrers should be deleted if defined. func WithManifestCheckReferrers() ManifestOpts { return func(config *ManifestConfig) { config.CheckReferrers = true } } -// WithManifestChild indicates the API call is on a child manifest -// This is used internally when copying multi-platform manifests -// This bypasses tracking of an untagged digest in ocidir which is needed for garbage collection +// WithManifestChild indicates the API call is on a child manifest. +// This is used internally when copying multi-platform manifests. +// This bypasses tracking of an untagged digest in ocidir which is needed for garbage collection. func WithManifestChild() ManifestOpts { return func(config *ManifestConfig) { config.Child = true } } -// WithManifest is used to pass the manifest to a method to avoid an extra GET request -// This is used on a delete to check for referrers +// WithManifest is used to pass the manifest to a method to avoid an extra GET request. +// This is used on a delete to check for referrers. func WithManifest(m manifest.Manifest) ManifestOpts { return func(mc *ManifestConfig) { mc.Manifest = m } } -// ReferrerConfig is used by schemes to import ReferrerOpts +// ReferrerConfig is used by schemes to import [ReferrerOpts]. type ReferrerConfig struct { MatchOpt types.MatchOpt // filter/sort results Platform string // get referrers for a specific platform } -// ReferrerOpts is used to set options on referrer APIs +// ReferrerOpts is used to set options on referrer APIs. type ReferrerOpts func(*ReferrerConfig) -// WithReferrerMatchOpt filters results using MatchOpt +// WithReferrerMatchOpt filters results using [types.MatchOpt]. func WithReferrerMatchOpt(mo types.MatchOpt) ReferrerOpts { return func(config *ReferrerConfig) { config.MatchOpt = mo } } -// WithReferrerPlatform gets referrers for a single platform from a multi-platform manifest +// WithReferrerPlatform gets referrers for a single platform from a multi-platform manifest. func WithReferrerPlatform(p string) ReferrerOpts { return func(config *ReferrerConfig) { config.Platform = p } } -// WithReferrerAT filters by a specific artifactType value +// WithReferrerAT filters by a specific artifactType value. // -// Deprecated: replace with WithReferrerMatchOpt +// Deprecated: replace with [WithReferrerMatchOpt]. func WithReferrerAT(at string) ReferrerOpts { return func(config *ReferrerConfig) { config.MatchOpt.ArtifactType = at } } -// WithReferrerAnnotations filters by a list of annotations, all of which must match +// WithReferrerAnnotations filters by a list of annotations, all of which must match. // -// Deprecated: replace with WithReferrerMatchOpt +// Deprecated: replace with [WithReferrerMatchOpt]. func WithReferrerAnnotations(annotations map[string]string) ReferrerOpts { return func(config *ReferrerConfig) { if config.MatchOpt.Annotations == nil { @@ -148,7 +148,7 @@ func WithReferrerAnnotations(annotations map[string]string) ReferrerOpts { // WithReferrerSort orders the resulting referrers listing according to a specified annotation. // -// Deprecated: replace with WithReferrerMatchOpt +// Deprecated: replace with [WithReferrerMatchOpt]. func WithReferrerSort(annotation string, desc bool) ReferrerOpts { return func(config *ReferrerConfig) { config.MatchOpt.SortAnnotation = annotation @@ -156,7 +156,7 @@ func WithReferrerSort(annotation string, desc bool) ReferrerOpts { } } -// ReferrerFilter filters the referrer list according to the config +// ReferrerFilter filters the referrer list according to the config. func ReferrerFilter(config ReferrerConfig, rlIn referrer.ReferrerList) referrer.ReferrerList { return referrer.ReferrerList{ Subject: rlIn.Subject, @@ -167,50 +167,50 @@ func ReferrerFilter(config ReferrerConfig, rlIn referrer.ReferrerList) referrer. } } -// RepoConfig is used by schemes to import RepoOpts +// RepoConfig is used by schemes to import [RepoOpts]. type RepoConfig struct { Limit int Last string } -// RepoOpts is used to set options on repo APIs +// RepoOpts is used to set options on repo APIs. type RepoOpts func(*RepoConfig) -// WithRepoLimit passes a maximum number of repositories to return to the repository list API -// Registries may ignore this +// WithRepoLimit passes a maximum number of repositories to return to the repository list API. +// Registries may ignore this. func WithRepoLimit(l int) RepoOpts { return func(config *RepoConfig) { config.Limit = l } } -// WithRepoLast passes the last received repository for requesting the next batch of repositories -// Registries may ignore this +// WithRepoLast passes the last received repository for requesting the next batch of repositories. +// Registries may ignore this. func WithRepoLast(l string) RepoOpts { return func(config *RepoConfig) { config.Last = l } } -// TagConfig is used by schemes to import TagOpts +// TagConfig is used by schemes to import [TagOpts]. type TagConfig struct { Limit int Last string } -// TagOpts is used to set options on tag APIs +// TagOpts is used to set options on tag APIs. type TagOpts func(*TagConfig) -// WithTagLimit passes a maximum number of tags to return to the tag list API -// Registries may ignore this +// WithTagLimit passes a maximum number of tags to return to the tag list API. +// Registries may ignore this. func WithTagLimit(limit int) TagOpts { return func(t *TagConfig) { t.Limit = limit } } -// WithTagLast passes the last received tag for requesting the next batch of tags -// Registries may ignore this +// WithTagLast passes the last received tag for requesting the next batch of tags. +// Registries may ignore this. func WithTagLast(last string) TagOpts { return func(t *TagConfig) { t.Last = last diff --git a/types/blob/common.go b/types/blob/common.go index 6101b40..3b0f18c 100644 --- a/types/blob/common.go +++ b/types/blob/common.go @@ -31,21 +31,21 @@ func (c *BCommon) GetDescriptor() types.Descriptor { // Digest returns the provided or calculated digest of the blob. // -// Deprecated: Digest should be replaced by GetDescriptor().Digest. +// Deprecated: Digest should be replaced by GetDescriptor().Digest, see [GetDescriptor]. func (c *BCommon) Digest() digest.Digest { return c.desc.Digest } // Length returns the provided or calculated length of the blob. // -// Deprecated: Length should be replaced by GetDescriptor().Size. +// Deprecated: Length should be replaced by GetDescriptor().Size, see [GetDescriptor]. func (c *BCommon) Length() int64 { return c.desc.Size } // MediaType returns the Content-Type header received from the registry. // -// Deprecated: MediaType should be replaced by GetDescriptor().MediaType. +// Deprecated: MediaType should be replaced by GetDescriptor().MediaType, see [GetDescriptor]. func (c *BCommon) MediaType() string { return c.desc.MediaType } diff --git a/types/manifest/docker1.go b/types/manifest/docker1.go index 6292534..e7d4a8a 100644 --- a/types/manifest/docker1.go +++ b/types/manifest/docker1.go @@ -17,9 +17,9 @@ import ( ) const ( - // MediaTypeDocker1Manifest deprecated media type for docker schema1 manifests + // MediaTypeDocker1Manifest deprecated media type for docker schema1 manifests. MediaTypeDocker1Manifest = "application/vnd.docker.distribution.manifest.v1+json" - // MediaTypeDocker1ManifestSigned is a deprecated schema1 manifest with jws signing + // MediaTypeDocker1ManifestSigned is a deprecated schema1 manifest with jws signing. MediaTypeDocker1ManifestSigned = "application/vnd.docker.distribution.manifest.v1+prettyjws" ) diff --git a/types/manifest/manifest.go b/types/manifest/manifest.go index 11069e6..e802bf1 100644 --- a/types/manifest/manifest.go +++ b/types/manifest/manifest.go @@ -10,7 +10,7 @@ import ( "strconv" "strings" - // crypto libraries included for go-digest + // Crypto libraries are included for go-digest. _ "crypto/sha256" _ "crypto/sha512" @@ -36,40 +36,44 @@ type Manifest interface { RawHeaders() (http.Header, error) SetOrig(interface{}) error - // Deprecated: GetConfig should be accessed using Imager interface + // Deprecated: GetConfig should be accessed using [Imager] interface. GetConfig() (types.Descriptor, error) - // Deprecated: GetLayers should be accessed using Imager interface + // Deprecated: GetLayers should be accessed using [Imager] interface. GetLayers() ([]types.Descriptor, error) - // Deprecated: GetManifestList should be accessed using Indexer interface + // Deprecated: GetManifestList should be accessed using [Indexer] interface. GetManifestList() ([]types.Descriptor, error) - // Deprecated: GetConfigDigest should be replaced with GetConfig + // Deprecated: GetConfigDigest should be replaced with [GetConfig]. GetConfigDigest() (digest.Digest, error) - // Deprecated: GetDigest should be replaced with GetDescriptor().Digest + // Deprecated: GetDigest should be replaced with GetDescriptor().Digest, see [GetDescriptor]. GetDigest() digest.Digest - // Deprecated: GetMediaType should be replaced with GetDescriptor().MediaType + // Deprecated: GetMediaType should be replaced with GetDescriptor().MediaType, see [GetDescriptor]. GetMediaType() string - // Deprecated: GetPlatformDesc method should be replaced with manifest.GetPlatformDesc function + // Deprecated: GetPlatformDesc method should be replaced with [manifest.GetPlatformDesc]. GetPlatformDesc(p *platform.Platform) (*types.Descriptor, error) - // Deprecated: GetPlatformList method should be replaced with manifest.GetPlatformList function + // Deprecated: GetPlatformList method should be replaced with [manifest.GetPlatformList]. GetPlatformList() ([]*platform.Platform, error) - // Deprecated: GetRateLimit method should be replaced with manifest.GetRateLimit function + // Deprecated: GetRateLimit method should be replaced with [manifest.GetRateLimit]. GetRateLimit() types.RateLimit - // Deprecated: HasRateLimit method should be replaced with manifest.HasRateLimit function + // Deprecated: HasRateLimit method should be replaced with [manifest.HasRateLimit]. HasRateLimit() bool } +// Annotator is used by manifests that support annotations. +// Note this will work for Docker manifests despite the spec not officially supporting it. type Annotator interface { GetAnnotations() (map[string]string, error) SetAnnotation(key, val string) error } +// Indexer is used by manifests that contain a manifest list. type Indexer interface { GetManifestList() ([]types.Descriptor, error) SetManifestList(dl []types.Descriptor) error } +// Imager is used by manifests packaging an image. type Imager interface { GetConfig() (types.Descriptor, error) GetLayers() ([]types.Descriptor, error) @@ -77,6 +81,7 @@ type Imager interface { SetLayers(dl []types.Descriptor) error } +// Subjecter is used by manifests that may have a subject field. type Subjecter interface { GetSubject() (*types.Descriptor, error) SetSubject(d *types.Descriptor) error @@ -91,7 +96,7 @@ type manifestConfig struct { } type Opts func(*manifestConfig) -// New creates a new manifest based on provided options +// New creates a new manifest based on provided options. func New(opts ...Opts) (Manifest, error) { mc := manifestConfig{} for _, opt := range opts { @@ -123,54 +128,54 @@ func New(opts ...Opts) (Manifest, error) { return fromCommon(c) } -// WithDesc specifies the descriptor for the manifest +// WithDesc specifies the descriptor for the manifest. func WithDesc(desc types.Descriptor) Opts { return func(mc *manifestConfig) { mc.desc = desc } } -// WithHeader provides the headers from the response when pulling the manifest +// WithHeader provides the headers from the response when pulling the manifest. func WithHeader(header http.Header) Opts { return func(mc *manifestConfig) { mc.header = header } } -// WithOrig provides the original manifest variable +// WithOrig provides the original manifest variable. func WithOrig(orig interface{}) Opts { return func(mc *manifestConfig) { mc.orig = orig } } -// WithRaw provides the manifest bytes or HTTP response body +// WithRaw provides the manifest bytes or HTTP response body. func WithRaw(raw []byte) Opts { return func(mc *manifestConfig) { mc.raw = raw } } -// WithRef provides the reference used to get the manifest +// WithRef provides the reference used to get the manifest. func WithRef(r ref.Ref) Opts { return func(mc *manifestConfig) { mc.r = r } } -// GetDigest returns the digest from the manifest descriptor +// GetDigest returns the digest from the manifest descriptor. func GetDigest(m Manifest) digest.Digest { d := m.GetDescriptor() return d.Digest } -// GetMediaType returns the media type from the manifest descriptor +// GetMediaType returns the media type from the manifest descriptor. func GetMediaType(m Manifest) string { d := m.GetDescriptor() return d.MediaType } -// GetPlatformDesc returns the descriptor for a specific platform from an index +// GetPlatformDesc returns the descriptor for a specific platform from an index. func GetPlatformDesc(m Manifest, p *platform.Platform) (*types.Descriptor, error) { dl, err := m.GetManifestList() if err != nil { @@ -186,7 +191,7 @@ func GetPlatformDesc(m Manifest, p *platform.Platform) (*types.Descriptor, error return &d, nil } -// GetPlatformList returns the list of platforms from an index +// GetPlatformList returns the list of platforms from an index. func GetPlatformList(m Manifest) ([]*platform.Platform, error) { dl, err := m.GetManifestList() if err != nil { @@ -201,7 +206,7 @@ func GetPlatformList(m Manifest) ([]*platform.Platform, error) { return l, nil } -// GetRateLimit returns the current rate limit seen in headers +// GetRateLimit returns the current rate limit seen in headers. func GetRateLimit(m Manifest) types.RateLimit { rl := types.RateLimit{} header, err := m.RawHeaders() @@ -248,12 +253,13 @@ func GetRateLimit(m Manifest) types.RateLimit { return rl } -// HasRateLimit indicates whether the rate limit is set and available +// HasRateLimit indicates whether the rate limit is set and available. func HasRateLimit(m Manifest) bool { rl := GetRateLimit(m) return rl.Set } +// OCIIndexFromAny converts manifest lists to an OCI index. func OCIIndexFromAny(orig interface{}) (v1.Index, error) { ociI := v1.Index{ Versioned: v1.IndexSchemaVersion, @@ -271,6 +277,7 @@ func OCIIndexFromAny(orig interface{}) (v1.Index, error) { return ociI, nil } +// OCIIndexToAny converts from an OCI index back to the manifest list. func OCIIndexToAny(ociI v1.Index, origP interface{}) error { // reflect is used to handle both *interface{} and *Manifest rv := reflect.ValueOf(origP) @@ -298,6 +305,7 @@ func OCIIndexToAny(ociI v1.Index, origP interface{}) error { return nil } +// OCIManifestFromAny converts an image manifest to an OCI manifest. func OCIManifestFromAny(orig interface{}) (v1.Manifest, error) { ociM := v1.Manifest{ Versioned: v1.ManifestSchemaVersion, @@ -317,6 +325,7 @@ func OCIManifestFromAny(orig interface{}) (v1.Manifest, error) { return ociM, nil } +// OCIManifestToAny converts an OCI manifest back to the image manifest. func OCIManifestToAny(ociM v1.Manifest, origP interface{}) error { // reflect is used to handle both *interface{} and *Manifest rv := reflect.ValueOf(origP) @@ -435,6 +444,7 @@ func fromOrig(c common, orig interface{}) (Manifest, error) { return m, nil } +// fromCommon is used to create a manifest when the underlying manifest struct is not provided. func fromCommon(c common) (Manifest, error) { var err error var m Manifest diff --git a/types/mediatype.go b/types/mediatype.go index fb41558..16a74c9 100644 --- a/types/mediatype.go +++ b/types/mediatype.go @@ -3,47 +3,47 @@ package types import "strings" const ( - // MediaTypeDocker1Manifest deprecated media type for docker schema1 manifests + // MediaTypeDocker1Manifest deprecated media type for docker schema1 manifests. MediaTypeDocker1Manifest = "application/vnd.docker.distribution.manifest.v1+json" - // MediaTypeDocker1ManifestSigned is a deprecated schema1 manifest with jws signing + // MediaTypeDocker1ManifestSigned is a deprecated schema1 manifest with jws signing. MediaTypeDocker1ManifestSigned = "application/vnd.docker.distribution.manifest.v1+prettyjws" - // MediaTypeDocker2Manifest is the media type when pulling manifests from a v2 registry + // MediaTypeDocker2Manifest is the media type when pulling manifests from a v2 registry. MediaTypeDocker2Manifest = "application/vnd.docker.distribution.manifest.v2+json" - // MediaTypeDocker2ManifestList is the media type when pulling a manifest list from a v2 registry + // MediaTypeDocker2ManifestList is the media type when pulling a manifest list from a v2 registry. MediaTypeDocker2ManifestList = "application/vnd.docker.distribution.manifest.list.v2+json" - // MediaTypeDocker2ImageConfig is for the configuration json object media type + // MediaTypeDocker2ImageConfig is for the configuration json object media type. MediaTypeDocker2ImageConfig = "application/vnd.docker.container.image.v1+json" - // MediaTypeOCI1Artifact EXPERIMENTAL OCI v1 artifact media type + // MediaTypeOCI1Artifact EXPERIMENTAL OCI v1 artifact media type. MediaTypeOCI1Artifact = "application/vnd.oci.artifact.manifest.v1+json" - // MediaTypeOCI1Manifest OCI v1 manifest media type + // MediaTypeOCI1Manifest OCI v1 manifest media type. MediaTypeOCI1Manifest = "application/vnd.oci.image.manifest.v1+json" - // MediaTypeOCI1ManifestList OCI v1 manifest list media type + // MediaTypeOCI1ManifestList OCI v1 manifest list media type. MediaTypeOCI1ManifestList = "application/vnd.oci.image.index.v1+json" - // MediaTypeOCI1ImageConfig OCI v1 configuration json object media type + // MediaTypeOCI1ImageConfig OCI v1 configuration json object media type. MediaTypeOCI1ImageConfig = "application/vnd.oci.image.config.v1+json" - // MediaTypeDocker2LayerGzip is the default compressed layer for docker schema2 + // MediaTypeDocker2LayerGzip is the default compressed layer for docker schema2. MediaTypeDocker2LayerGzip = "application/vnd.docker.image.rootfs.diff.tar.gzip" - // MediaTypeDocker2ForeignLayer is the default compressed layer for foreign layers in docker schema2 + // MediaTypeDocker2ForeignLayer is the default compressed layer for foreign layers in docker schema2. MediaTypeDocker2ForeignLayer = "application/vnd.docker.image.rootfs.foreign.diff.tar.gzip" - // MediaTypeOCI1Layer is the uncompressed layer for OCIv1 + // MediaTypeOCI1Layer is the uncompressed layer for OCIv1. MediaTypeOCI1Layer = "application/vnd.oci.image.layer.v1.tar" - // MediaTypeOCI1LayerGzip is the gzip compressed layer for OCI v1 + // MediaTypeOCI1LayerGzip is the gzip compressed layer for OCI v1. MediaTypeOCI1LayerGzip = "application/vnd.oci.image.layer.v1.tar+gzip" - // MediaTypeOCI1LayerZstd is the zstd compressed layer for OCI v1 + // MediaTypeOCI1LayerZstd is the zstd compressed layer for OCI v1. MediaTypeOCI1LayerZstd = "application/vnd.oci.image.layer.v1.tar+zstd" - // MediaTypeOCI1ForeignLayer is the foreign layer for OCI v1 + // MediaTypeOCI1ForeignLayer is the foreign layer for OCI v1. MediaTypeOCI1ForeignLayer = "application/vnd.oci.image.layer.nondistributable.v1.tar" - // MediaTypeOCI1ForeignLayerGzip is the gzip compressed foreign layer for OCI v1 + // MediaTypeOCI1ForeignLayerGzip is the gzip compressed foreign layer for OCI v1. MediaTypeOCI1ForeignLayerGzip = "application/vnd.oci.image.layer.nondistributable.v1.tar+gzip" - // MediaTypeOCI1ForeignLayerZstd is the zstd compressed foreign layer for OCI v1 + // MediaTypeOCI1ForeignLayerZstd is the zstd compressed foreign layer for OCI v1. MediaTypeOCI1ForeignLayerZstd = "application/vnd.oci.image.layer.nondistributable.v1.tar+zstd" - // MediaTypeOCI1Empty is used for blobs containing the empty JSON data `{}` + // MediaTypeOCI1Empty is used for blobs containing the empty JSON data `{}`. MediaTypeOCI1Empty = "application/vnd.oci.empty.v1+json" - // MediaTypeBuildkitCacheConfig is used by buildkit cache images + // MediaTypeBuildkitCacheConfig is used by buildkit cache images. MediaTypeBuildkitCacheConfig = "application/vnd.buildkit.cacheconfig.v0" ) -// MediaTypeBase cleans the Content-Type header to return only the lower case base media type +// MediaTypeBase cleans the Content-Type header to return only the lower case base media type. func MediaTypeBase(orig string) string { base, _, _ := strings.Cut(orig, ";") return strings.TrimSpace(strings.ToLower(base))