Skip to content

Commit af2603f

Browse files
authored
feat(remote): add WithReferrersTagFallback option (#2366)
Pushing a manifest with a subject to a registry that lacks the Referrers API maintains an index under the fallback tag scheme, and Referrers reads from it. Some callers want to require the Referrers API instead, so add an option to disable the fallback and fail when the API is unavailable. The default keeps the fallback enabled.
1 parent fb19695 commit af2603f

5 files changed

Lines changed: 203 additions & 19 deletions

File tree

‎pkg/v1/remote/options.go‎

Lines changed: 30 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ type options struct {
4646
retryPredicate retry.Predicate
4747
retryStatusCodes []int
4848
limiter *pullLimiter
49+
referrersTagFallback bool
4950

5051
// Only these options can overwrite Reuse()d options.
5152
platform v1.Platform
@@ -108,6 +109,8 @@ const (
108109
// ECR returns an error if n > 1000:
109110
// https://github.com/google/go-containerregistry/issues/1091
110111
defaultPageSize = 1000
112+
113+
defaultReferrersTagFallback = true
111114
)
112115

113116
// DefaultTransport is based on http.DefaultTransport with modifications
@@ -129,14 +132,15 @@ var DefaultTransport http.RoundTripper = &http.Transport{
129132

130133
func makeOptions(opts ...Option) (*options, error) {
131134
o := &options{
132-
transport: DefaultTransport,
133-
platform: defaultPlatform,
134-
context: context.Background(),
135-
jobs: defaultJobs,
136-
pageSize: defaultPageSize,
137-
retryPredicate: defaultRetryPredicate,
138-
retryBackoff: defaultRetryBackoff,
139-
retryStatusCodes: defaultRetryStatusCodes,
135+
transport: DefaultTransport,
136+
platform: defaultPlatform,
137+
context: context.Background(),
138+
jobs: defaultJobs,
139+
pageSize: defaultPageSize,
140+
retryPredicate: defaultRetryPredicate,
141+
retryBackoff: defaultRetryBackoff,
142+
retryStatusCodes: defaultRetryStatusCodes,
143+
referrersTagFallback: defaultReferrersTagFallback,
140144
}
141145

142146
for _, option := range opts {
@@ -328,6 +332,24 @@ func WithRetryStatusCodes(codes ...int) Option {
328332
}
329333
}
330334

335+
// WithReferrersTagFallback toggles the referrers tag fallback scheme, see:
336+
// https://github.com/opencontainers/distribution-spec/blob/main/spec.md#referrers-tag-schema
337+
//
338+
// When enabled, pushing a manifest with a subject to a registry that doesn't
339+
// support the Referrers API maintains an image index of referrers under a
340+
// fallback tag, and listing referrers reads from that tag. When disabled,
341+
// the Referrers API is required: pushing a manifest with a subject and
342+
// listing referrers both fail against a registry that doesn't support it,
343+
// rather than falling back to the tag scheme.
344+
//
345+
// The default is true.
346+
func WithReferrersTagFallback(enabled bool) Option {
347+
return func(o *options) error {
348+
o.referrersTagFallback = enabled
349+
return nil
350+
}
351+
}
352+
331353
// WithFilter sets the filter querystring for HTTP operations.
332354
func WithFilter(key string, value string) Option {
333355
return func(o *options) error {

‎pkg/v1/remote/puller.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -218,5 +218,5 @@ func (p *Puller) referrers(ctx context.Context, d name.Digest, filter map[string
218218
if err != nil {
219219
return nil, err
220220
}
221-
return f.fetchReferrers(ctx, filter, d)
221+
return f.fetchReferrers(ctx, filter, d, p.o.referrersTagFallback)
222222
}

‎pkg/v1/remote/referrers.go‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import (
1818
"bytes"
1919
"context"
2020
"errors"
21+
"fmt"
2122
"net/http"
2223
"strings"
2324

@@ -46,7 +47,7 @@ func fallbackTag(d name.Digest) name.Tag {
4647
return d.Context().Tag(strings.Replace(d.DigestStr(), ":", "-", 1))
4748
}
4849

49-
func (f *fetcher) fetchReferrers(ctx context.Context, filter map[string]string, d name.Digest) (v1.ImageIndex, error) {
50+
func (f *fetcher) fetchReferrers(ctx context.Context, filter map[string]string, d name.Digest, tagFallback bool) (v1.ImageIndex, error) {
5051
// Check the Referrers API endpoint first.
5152
u := f.url("referrers", d.DigestStr())
5253
req, err := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)
@@ -72,6 +73,9 @@ func (f *fetcher) fetchReferrers(ctx context.Context, filter map[string]string,
7273
return nil, err
7374
}
7475
} else {
76+
if !tagFallback {
77+
return nil, fmt.Errorf("registry %s does not support the Referrers API and the referrers tag fallback is disabled", d.Context().RegistryStr())
78+
}
7579
// The registry doesn't support the Referrers API endpoint, so we'll use the fallback tag scheme.
7680
b, _, err = f.fetchManifest(ctx, fallbackTag(d), []types.MediaType{types.OCIImageIndex})
7781
var terr *transport.Error

‎pkg/v1/remote/referrers_test.go‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,13 @@
1515
package remote_test
1616

1717
import (
18+
"errors"
1819
"fmt"
20+
"net/http"
1921
"net/http/httptest"
2022
"net/url"
23+
"strings"
24+
"sync"
2125
"testing"
2226

2327
"github.com/google/go-cmp/cmp"
@@ -27,6 +31,7 @@ import (
2731
"github.com/google/go-containerregistry/pkg/v1/mutate"
2832
"github.com/google/go-containerregistry/pkg/v1/random"
2933
"github.com/google/go-containerregistry/pkg/v1/remote"
34+
"github.com/google/go-containerregistry/pkg/v1/remote/transport"
3035
"github.com/google/go-containerregistry/pkg/v1/types"
3136
)
3237

@@ -215,3 +220,150 @@ func TestReferrers(t *testing.T) {
215220
}
216221
}
217222
}
223+
224+
func TestReferrersTagFallbackDisabled(t *testing.T) {
225+
// Push a subject image and an image referring to it, with the fallback
226+
// tag scheme disabled.
227+
pushWithSubject := func(t *testing.T, host string) (rootDigest v1.Hash, leafDigest v1.Hash, err error) {
228+
rootRef, err := name.ParseReference(fmt.Sprintf("%s/repo:root", host))
229+
if err != nil {
230+
t.Fatal(err)
231+
}
232+
rootImg, err := random.Image(10, 10)
233+
if err != nil {
234+
t.Fatal(err)
235+
}
236+
if err := remote.Write(rootRef, rootImg, remote.WithReferrersTagFallback(false)); err != nil {
237+
t.Fatal(err)
238+
}
239+
rootDigest, err = rootImg.Digest()
240+
if err != nil {
241+
t.Fatal(err)
242+
}
243+
rootSize, err := rootImg.Size()
244+
if err != nil {
245+
t.Fatal(err)
246+
}
247+
rootMediaType, err := rootImg.MediaType()
248+
if err != nil {
249+
t.Fatal(err)
250+
}
251+
252+
leafRef, err := name.ParseReference(fmt.Sprintf("%s/repo:leaf", host))
253+
if err != nil {
254+
t.Fatal(err)
255+
}
256+
leafImg, err := random.Image(20, 20)
257+
if err != nil {
258+
t.Fatal(err)
259+
}
260+
leafImg = mutate.Subject(leafImg, v1.Descriptor{
261+
Digest: rootDigest,
262+
Size: rootSize,
263+
MediaType: rootMediaType,
264+
}).(v1.Image)
265+
leafDigest, err = leafImg.Digest()
266+
if err != nil {
267+
t.Fatal(err)
268+
}
269+
return rootDigest, leafDigest, remote.Write(leafRef, leafImg, remote.WithReferrersTagFallback(false))
270+
}
271+
272+
// The fallback tag should never be created with the fallback disabled.
273+
checkNoFallbackTag := func(t *testing.T, host string, rootDigest v1.Hash) {
274+
fallbackRef, err := name.ParseReference(fmt.Sprintf("%s/repo:sha256-%s", host, rootDigest.Hex))
275+
if err != nil {
276+
t.Fatal(err)
277+
}
278+
if _, err := remote.Head(fallbackRef); err == nil {
279+
t.Errorf("Head(%q) succeeded, want NotFound", fallbackRef)
280+
} else {
281+
var terr *transport.Error
282+
if !errors.As(err, &terr) || terr.StatusCode != http.StatusNotFound {
283+
t.Errorf("Head(%q) = %v, want NotFound", fallbackRef, err)
284+
}
285+
}
286+
}
287+
288+
referrersDigest := func(t *testing.T, host string, rootDigest v1.Hash) name.Digest {
289+
repo, err := name.NewRepository(fmt.Sprintf("%s/repo", host))
290+
if err != nil {
291+
t.Fatal(err)
292+
}
293+
return repo.Digest(rootDigest.String())
294+
}
295+
296+
t.Run("registry without referrers API", func(t *testing.T) {
297+
// An OCI 1.0 registry (without referrers API), instrumented to record
298+
// requests to the referrers endpoint.
299+
reg := registry.New()
300+
var mu sync.Mutex
301+
referrersProbes := 0
302+
s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
303+
if strings.Contains(r.URL.Path, "/referrers/") {
304+
mu.Lock()
305+
referrersProbes++
306+
mu.Unlock()
307+
}
308+
reg.ServeHTTP(w, r)
309+
}))
310+
defer s.Close()
311+
u, err := url.Parse(s.URL)
312+
if err != nil {
313+
t.Fatal(err)
314+
}
315+
316+
// Pushing a subject-bearing manifest requires the Referrers API.
317+
rootDigest, _, err := pushWithSubject(t, u.Host)
318+
if err == nil {
319+
t.Fatal("Write() succeeded, want error")
320+
} else if !strings.Contains(err.Error(), "referrers tag fallback is disabled") {
321+
t.Fatalf("Write() = %v, want referrers tag fallback error", err)
322+
}
323+
324+
mu.Lock()
325+
probes := referrersProbes
326+
mu.Unlock()
327+
if probes != 1 {
328+
t.Errorf("pushing probed the referrers endpoint %d times, want 1", probes)
329+
}
330+
331+
checkNoFallbackTag(t, u.Host, rootDigest)
332+
333+
// Listing referrers requires the Referrers API too.
334+
if _, err := remote.Referrers(referrersDigest(t, u.Host, rootDigest), remote.WithReferrersTagFallback(false)); err == nil {
335+
t.Fatal("Referrers() succeeded, want error")
336+
} else if !strings.Contains(err.Error(), "referrers tag fallback is disabled") {
337+
t.Fatalf("Referrers() = %v, want referrers tag fallback error", err)
338+
}
339+
})
340+
341+
t.Run("registry with referrers API", func(t *testing.T) {
342+
s := httptest.NewServer(registry.New(registry.WithReferrersSupport(true)))
343+
defer s.Close()
344+
u, err := url.Parse(s.URL)
345+
if err != nil {
346+
t.Fatal(err)
347+
}
348+
349+
rootDigest, leafDigest, err := pushWithSubject(t, u.Host)
350+
if err != nil {
351+
t.Fatal(err)
352+
}
353+
354+
checkNoFallbackTag(t, u.Host, rootDigest)
355+
356+
// The registry serves the referrer natively.
357+
index, err := remote.Referrers(referrersDigest(t, u.Host, rootDigest), remote.WithReferrersTagFallback(false))
358+
if err != nil {
359+
t.Fatal(err)
360+
}
361+
m, err := index.IndexManifest()
362+
if err != nil {
363+
t.Fatal(err)
364+
}
365+
if len(m.Manifests) != 1 || m.Manifests[0].Digest != leafDigest {
366+
t.Fatalf("referrers = %v, want one entry for %s", m.Manifests, leafDigest)
367+
}
368+
})
369+
}

‎pkg/v1/remote/write.go‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ type writer struct {
6161
backoff Backoff
6262
predicate retry.Predicate
6363

64+
referrersTagFallback bool
65+
6466
scopeLock sync.Mutex
6567
// Keep track of scopes that we have already requested.
6668
scopeSet map[string]struct{}
@@ -106,15 +108,16 @@ func makeWriter(ctx context.Context, repo name.Repository, ls []v1.Layer, o *opt
106108
scopeSet[scope] = struct{}{}
107109
}
108110
return &writer{
109-
repo: repo,
110-
client: &http.Client{Transport: tr},
111-
auth: auth,
112-
transport: o.transport,
113-
progress: o.progress,
114-
backoff: o.retryBackoff,
115-
predicate: o.retryPredicate,
116-
scopes: scopes,
117-
scopeSet: scopeSet,
111+
repo: repo,
112+
client: &http.Client{Transport: tr},
113+
auth: auth,
114+
transport: o.transport,
115+
progress: o.progress,
116+
backoff: o.retryBackoff,
117+
predicate: o.retryPredicate,
118+
referrersTagFallback: o.referrersTagFallback,
119+
scopes: scopes,
120+
scopeSet: scopeSet,
118121
}, nil
119122
}
120123

@@ -527,6 +530,9 @@ func (w *writer) commitSubjectReferrers(ctx context.Context, sub name.Digest, ad
527530
// The registry supports Referrers API. The registry is responsible for updating the referrers list.
528531
return nil
529532
}
533+
if !w.referrersTagFallback {
534+
return fmt.Errorf("registry %s does not support the Referrers API and the referrers tag fallback is disabled", w.repo.RegistryStr())
535+
}
530536

531537
// The registry doesn't support Referrers API, we need to update the manifest tagged with the fallback tag.
532538
// Make the request to GET the current manifest.

0 commit comments

Comments
 (0)