From 3a2e0c1c24493f07db90e3cda4fa610718a454b2 Mon Sep 17 00:00:00 2001 From: "Lixia (Sylvia) Lei" Date: Wed, 2 Aug 2023 16:37:07 +0800 Subject: [PATCH] docs: update links (#563) Resolves: #554 Signed-off-by: Lixia (Sylvia) Lei --- content/oci/oci.go | 10 +++---- content/oci/readonlyoci.go | 2 +- content/oci/readonlystorage.go | 2 +- content/oci/storage.go | 2 +- registry/reference.go | 8 ++++-- registry/remote/errcode/errors.go | 6 ++-- registry/remote/referrers.go | 2 +- registry/remote/registry.go | 2 +- registry/remote/repository.go | 47 ++++++++++++++++--------------- registry/remote/url.go | 2 +- registry/repository.go | 9 ++++-- 11 files changed, 49 insertions(+), 43 deletions(-) diff --git a/content/oci/oci.go b/content/oci/oci.go index 5b473eeb..97ba6de5 100644 --- a/content/oci/oci.go +++ b/content/oci/oci.go @@ -14,7 +14,7 @@ limitations under the License. */ // Package oci provides access to an OCI content store. -// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md +// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md package oci import ( @@ -40,17 +40,17 @@ import ( // ociImageIndexFile is the file name of the index // from the OCI Image Layout Specification. -// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md#indexjson-file +// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md#indexjson-file const ociImageIndexFile = "index.json" // ociBlobsDir is the name of the blobs directory // from the OCI Image Layout Specification. -// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md#content +// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md#content const ociBlobsDir = "blobs" // Store implements `oras.Target`, and represents a content store // based on file system with the OCI-Image layout. -// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md +// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md type Store struct { // AutoSaveIndex controls if the OCI store will automatically save the index // file on each Tag() call. @@ -135,7 +135,7 @@ func (s *Store) Exists(ctx context.Context, target ocispec.Descriptor) (bool, er // Tag tags a descriptor with a reference string. // reference should be a valid tag (e.g. "latest"). -// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md#indexjson-file +// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md#indexjson-file func (s *Store) Tag(ctx context.Context, desc ocispec.Descriptor, reference string) error { if err := validateReference(reference); err != nil { return err diff --git a/content/oci/readonlyoci.go b/content/oci/readonlyoci.go index f908d169..eb94f61c 100644 --- a/content/oci/readonlyoci.go +++ b/content/oci/readonlyoci.go @@ -36,7 +36,7 @@ import ( // ReadOnlyStore implements `oras.ReadonlyTarget`, and represents a read-only // content store based on file system with the OCI-Image layout. -// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md +// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md type ReadOnlyStore struct { fsys fs.FS storage content.ReadOnlyStorage diff --git a/content/oci/readonlystorage.go b/content/oci/readonlystorage.go index 3cab94fa..b5e53039 100644 --- a/content/oci/readonlystorage.go +++ b/content/oci/readonlystorage.go @@ -31,7 +31,7 @@ import ( // ReadOnlyStorage is a read-only CAS based on file system with the OCI-Image // layout. -// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md +// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md type ReadOnlyStorage struct { fsys fs.FS } diff --git a/content/oci/storage.go b/content/oci/storage.go index 6b0e90a8..9d4d03b3 100644 --- a/content/oci/storage.go +++ b/content/oci/storage.go @@ -42,7 +42,7 @@ var bufPool = sync.Pool{ } // Storage is a CAS based on file system with the OCI-Image layout. -// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md +// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md type Storage struct { *ReadOnlyStorage // root is the root directory of the OCI layout. diff --git a/registry/reference.go b/registry/reference.go index cea579a1..7661a162 100644 --- a/registry/reference.go +++ b/registry/reference.go @@ -31,14 +31,16 @@ var ( // repository name set under OCI distribution spec is a subset of the docker // spec. For maximum compatability, the docker spec is verified client-side. // Further checks are left to the server-side. + // // References: - // - https://github.com/distribution/distribution/blob/v2.7.1/reference/regexp.go#L53 - // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#pulling-manifests + // - https://github.com/distribution/distribution/blob/v2.7.1/reference/regexp.go#L53 + // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pulling-manifests repositoryRegexp = regexp.MustCompile(`^[a-z0-9]+(?:(?:[._]|__|[-]*)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|[-]*)[a-z0-9]+)*)*$`) // tagRegexp checks the tag name. // The docker and OCI spec have the same regular expression. - // Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#pulling-manifests + // + // Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pulling-manifests tagRegexp = regexp.MustCompile(`^[\w][\w.-]{0,127}$`) ) diff --git a/registry/remote/errcode/errors.go b/registry/remote/errcode/errors.go index cf0018a0..fb192aa8 100644 --- a/registry/remote/errcode/errors.go +++ b/registry/remote/errcode/errors.go @@ -24,7 +24,7 @@ import ( ) // References: -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#error-codes +// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#error-codes // - https://docs.docker.com/registry/spec/api/#errors-2 const ( ErrorCodeBlobUnknown = "BLOB_UNKNOWN" @@ -45,7 +45,7 @@ const ( // Error represents a response inner error returned by the remote // registry. // References: -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#error-codes +// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#error-codes // - https://docs.docker.com/registry/spec/api/#errors-2 type Error struct { Code string `json:"code"` @@ -73,7 +73,7 @@ func (e Error) Error() string { // Errors represents a list of response inner errors returned by the remote // server. // References: -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#error-codes +// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#error-codes // - https://docs.docker.com/registry/spec/api/#errors-2 type Errors []Error diff --git a/registry/remote/referrers.go b/registry/remote/referrers.go index 8c304953..191db9d1 100644 --- a/registry/remote/referrers.go +++ b/registry/remote/referrers.go @@ -102,7 +102,7 @@ func (e *ReferrersError) IsReferrersIndexDelete() bool { // buildReferrersTag builds the referrers tag for the given manifest descriptor. // Format: - -// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#unavailable-referrers-api +// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#unavailable-referrers-api func buildReferrersTag(desc ocispec.Descriptor) string { alg := desc.Digest.Algorithm().String() encoded := desc.Digest.Encoded() diff --git a/registry/remote/registry.go b/registry/remote/registry.go index c8c414f1..bd6a3b0d 100644 --- a/registry/remote/registry.go +++ b/registry/remote/registry.go @@ -79,7 +79,7 @@ func (r *Registry) client() Client { // // References: // - https://docs.docker.com/registry/spec/api/#base -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#api +// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#api func (r *Registry) Ping(ctx context.Context) error { url := buildRegistryBaseURL(r.PlainHTTP, r.Reference) req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) diff --git a/registry/remote/repository.go b/registry/remote/repository.go index c952edb3..794711ee 100644 --- a/registry/remote/repository.go +++ b/registry/remote/repository.go @@ -54,7 +54,7 @@ const ( // // References: // - https://docs.docker.com/registry/spec/api/#digest-header - // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#pull + // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pull headerDockerContentDigest = "Docker-Content-Digest" // headerOCIFiltersApplied is the "OCI-Filters-Applied" header. @@ -75,8 +75,8 @@ const ( // referrers. // // References: -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers +// - Latest spec: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers +// - Compatible spec: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers const filterTypeArtifactType = "artifactType" // Client is an interface for a HTTP client. @@ -119,7 +119,7 @@ type Repository struct { // ReferrerListPageSize specifies the page size when invoking the Referrers // API. // If zero, the page size is determined by the remote registry. - // Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers + // Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers ReferrerListPageSize int // MaxMetadataBytes specifies a limit on how many response bytes are allowed @@ -134,9 +134,9 @@ type Repository struct { // is successfully uploaded. // - If true, the old referrers index is kept. // By default, it is disabled (set to false). See also: - // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema - // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#pushing-manifests-with-subject - // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#deleting-manifests + // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#referrers-tag-schema + // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pushing-manifests-with-subject + // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#deleting-manifests SkipReferrersGC bool // NOTE: Must keep fields in sync with newRepositoryWithOptions function. @@ -197,9 +197,9 @@ func newRepositoryWithOptions(ref registry.Reference, opts *RepositoryOptions) ( // SetReferrersCapability returns ErrReferrersCapabilityAlreadySet if the // Referrers API capability has been already set. // - When the capability is set to true, the Referrers() function will always -// request the Referrers API. Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers +// request the Referrers API. Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers // - When the capability is set to false, the Referrers() function will always -// request the Referrers Tag. Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema +// request the Referrers Tag. Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#referrers-tag-schema // - When the capability is not set, the Referrers() function will automatically // determine which API to use. func (r *Repository) SetReferrersCapability(capable bool) error { @@ -358,7 +358,7 @@ func (r *Repository) ParseReference(reference string) (registry.Reference, error // of the Tags list. // // References: -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#content-discovery +// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#content-discovery // - https://docs.docker.com/registry/spec/api/#tags func (r *Repository) Tags(ctx context.Context, last string, fn func(tags []string) error) error { ctx = registryutil.WithScopeHint(ctx, r.Reference, auth.ActionPull) @@ -417,7 +417,7 @@ func (r *Repository) tags(ctx context.Context, last string, fn func(tags []strin // Predecessors returns the descriptors of image or artifact manifests directly // referencing the given manifest descriptor. // Predecessors internally leverages Referrers. -// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers +// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers func (r *Repository) Predecessors(ctx context.Context, desc ocispec.Descriptor) ([]ocispec.Descriptor, error) { var res []ocispec.Descriptor if err := r.Referrers(ctx, desc, "", func(referrers []ocispec.Descriptor) error { @@ -436,7 +436,7 @@ func (r *Repository) Predecessors(ctx context.Context, desc ocispec.Descriptor) // If artifactType is not empty, only referrers of the same artifact type are // fed to fn. // -// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers +// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers func (r *Repository) Referrers(ctx context.Context, desc ocispec.Descriptor, artifactType string, fn func(referrers []ocispec.Descriptor) error) error { state := r.loadReferrersState() if state == referrersStateUnsupported { @@ -527,8 +527,8 @@ func (r *Repository) referrersPageByAPI(ctx context.Context, artifactType string referrers := index.Manifests if artifactType != "" { // check both filters header and filters annotations for compatibility - // reference for filters header: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers - // reference for filters annotations: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers + // latest spec for filters header: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers + // older spec for filters annotations: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers filtersHeader := resp.Header.Get(headerOCIFiltersApplied) filtersAnnotation := index.Annotations[spec.AnnotationReferrersFiltersApplied] if !isReferrersFilterApplied(filtersHeader, filterTypeArtifactType) && @@ -549,7 +549,7 @@ func (r *Repository) referrersPageByAPI(ctx context.Context, artifactType string // referencing the given manifest descriptor by requesting referrers tag. // fn is called for the referrers result. If artifactType is not empty, // only referrers of the same artifact type are fed to fn. -// reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#backwards-compatibility +// reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#backwards-compatibility func (r *Repository) referrersByTagSchema(ctx context.Context, desc ocispec.Descriptor, artifactType string, fn func(referrers []ocispec.Descriptor) error) error { referrersTag := buildReferrersTag(desc) _, referrers, err := r.referrersFromIndex(ctx, referrersTag) @@ -762,7 +762,7 @@ func (s *blobStore) Mount(ctx context.Context, desc ocispec.Descriptor, fromRepo // push it. If the caller has provided a getContent function, we // can use that, otherwise pull the content from the source repository. // - // [spec]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#mounting-a-blob-from-another-repository + // [spec]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#mounting-a-blob-from-another-repository var r io.ReadCloser if getContent != nil { @@ -793,10 +793,11 @@ func (s *blobStore) sibling(otherRepoName string) *blobStore { // Push is done by conventional 2-step monolithic upload instead of a single // `POST` request for better overall performance. It also allows early fail on // authentication errors. +// // References: -// - https://docs.docker.com/registry/spec/api/#pushing-an-image -// - https://docs.docker.com/registry/spec/api/#initiate-blob-upload -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#pushing-a-blob-monolithically +// - https://docs.docker.com/registry/spec/api/#pushing-an-image +// - https://docs.docker.com/registry/spec/api/#initiate-blob-upload +// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pushing-a-blob-monolithically func (s *blobStore) Push(ctx context.Context, expected ocispec.Descriptor, content io.Reader) error { // start an upload // pushing usually requires both pull and push actions. @@ -1105,8 +1106,8 @@ func (s *manifestStore) deleteWithIndexing(ctx context.Context, target ocispec.D // on manifest delete. // // References: -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#deleting-manifests -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#deleting-manifests +// - Latest spec: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#deleting-manifests +// - Compatible spec: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#deleting-manifests func (s *manifestStore) indexReferrersForDelete(ctx context.Context, desc ocispec.Descriptor, manifestJSON []byte) error { var manifest struct { Subject *ocispec.Descriptor `json:"subject"` @@ -1334,8 +1335,8 @@ func (s *manifestStore) pushWithIndexing(ctx context.Context, expected ocispec.D // on manifest push. // // References: -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pushing-manifests-with-subject -// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#pushing-manifests-with-subject +// - Latest spec: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pushing-manifests-with-subject +// - Compatible spec: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#pushing-manifests-with-subject func (s *manifestStore) indexReferrersForPush(ctx context.Context, desc ocispec.Descriptor, manifestJSON []byte) error { var subject ocispec.Descriptor switch desc.MediaType { diff --git a/registry/remote/url.go b/registry/remote/url.go index d3eee3ee..74258de7 100644 --- a/registry/remote/url.go +++ b/registry/remote/url.go @@ -101,7 +101,7 @@ func buildRepositoryBlobMountURL(plainHTTP bool, ref registry.Reference, d diges // buildReferrersURL builds the URL for querying the Referrers API. // Format: :///v2//referrers/?artifactType= -// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers +// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers func buildReferrersURL(plainHTTP bool, ref registry.Reference, artifactType string) string { var query string if artifactType != "" { diff --git a/registry/repository.go b/registry/repository.go index 2dd7ff99..b75b7b8e 100644 --- a/registry/repository.go +++ b/registry/repository.go @@ -82,7 +82,7 @@ type ReferenceFetcher interface { } // ReferrerLister provides the Referrers API. -// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers +// Reference: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers type ReferrerLister interface { Referrers(ctx context.Context, desc ocispec.Descriptor, artifactType string, fn func(referrers []ocispec.Descriptor) error) error } @@ -93,16 +93,19 @@ type TagLister interface { // Since the returned tag list may be paginated by the underlying // implementation, a function should be passed in to process the paginated // tag list. + // // `last` argument is the `last` parameter when invoking the tags API. // If `last` is NOT empty, the entries in the response start after the // tag specified by `last`. Otherwise, the response starts from the top // of the Tags list. + // // Note: When implemented by a remote registry, the tags API is called. // However, not all registries supports pagination or conforms the // specification. + // // References: - // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#content-discovery - // - https://docs.docker.com/registry/spec/api/#tags + // - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#content-discovery + // - https://docs.docker.com/registry/spec/api/#tags // See also `Tags()` in this package. Tags(ctx context.Context, last string, fn func(tags []string) error) error }