options.go

Documentation: github.com/google/go-containerregistry/pkg/v1/remote

     1  // Copyright 2018 Google LLC All Rights Reserved.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //    http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package remote
    16  
    17  import (
    18  	"context"
    19  	"errors"
    20  	"io"
    21  	"net"
    22  	"net/http"
    23  	"syscall"
    24  	"time"
    25  
    26  	"github.com/google/go-containerregistry/internal/retry"
    27  	"github.com/google/go-containerregistry/pkg/authn"
    28  	"github.com/google/go-containerregistry/pkg/logs"
    29  	v1 "github.com/google/go-containerregistry/pkg/v1"
    30  	"github.com/google/go-containerregistry/pkg/v1/remote/transport"
    31  )
    32  
    33  // Option is a functional option for remote operations.
    34  type Option func(*options) error
    35  
    36  type options struct {
    37  	auth                           authn.Authenticator
    38  	keychain                       authn.Keychain
    39  	transport                      http.RoundTripper
    40  	context                        context.Context
    41  	jobs                           int
    42  	userAgent                      string
    43  	allowNondistributableArtifacts bool
    44  	progress                       *progress
    45  	retryBackoff                   Backoff
    46  	retryPredicate                 retry.Predicate
    47  	retryStatusCodes               []int
    48  
    49  	// Only these options can overwrite Reuse()d options.
    50  	platform v1.Platform
    51  	pageSize int
    52  	filter   map[string]string
    53  
    54  	// Set by Reuse, we currently store one or the other.
    55  	puller *Puller
    56  	pusher *Pusher
    57  }
    58  
    59  var defaultPlatform = v1.Platform{
    60  	Architecture: "amd64",
    61  	OS:           "linux",
    62  }
    63  
    64  // Backoff is an alias of retry.Backoff to expose this configuration option to consumers of this lib
    65  type Backoff = retry.Backoff
    66  
    67  var defaultRetryPredicate retry.Predicate = func(err error) bool {
    68  	// Various failure modes here, as we're often reading from and writing to
    69  	// the network.
    70  	if retry.IsTemporary(err) || errors.Is(err, io.ErrUnexpectedEOF) || errors.Is(err, io.EOF) || errors.Is(err, syscall.EPIPE) || errors.Is(err, syscall.ECONNRESET) || errors.Is(err, net.ErrClosed) {
    71  		logs.Warn.Printf("retrying %v", err)
    72  		return true
    73  	}
    74  	return false
    75  }
    76  
    77  // Try this three times, waiting 1s after first failure, 3s after second.
    78  var defaultRetryBackoff = Backoff{
    79  	Duration: 1.0 * time.Second,
    80  	Factor:   3.0,
    81  	Jitter:   0.1,
    82  	Steps:    3,
    83  }
    84  
    85  // Useful for tests
    86  var fastBackoff = Backoff{
    87  	Duration: 1.0 * time.Millisecond,
    88  	Factor:   3.0,
    89  	Jitter:   0.1,
    90  	Steps:    3,
    91  }
    92  
    93  var defaultRetryStatusCodes = []int{
    94  	http.StatusRequestTimeout,
    95  	http.StatusInternalServerError,
    96  	http.StatusBadGateway,
    97  	http.StatusServiceUnavailable,
    98  	http.StatusGatewayTimeout,
    99  	499, // nginx-specific, client closed request
   100  	522, // Cloudflare-specific, connection timeout
   101  }
   102  
   103  const (
   104  	defaultJobs = 4
   105  
   106  	// ECR returns an error if n > 1000:
   107  	// https://github.com/google/go-containerregistry/issues/1091
   108  	defaultPageSize = 1000
   109  )
   110  
   111  // DefaultTransport is based on http.DefaultTransport with modifications
   112  // documented inline below.
   113  var DefaultTransport http.RoundTripper = &http.Transport{
   114  	Proxy: http.ProxyFromEnvironment,
   115  	DialContext: (&net.Dialer{
   116  		Timeout:   30 * time.Second,
   117  		KeepAlive: 30 * time.Second,
   118  	}).DialContext,
   119  	ForceAttemptHTTP2:     true,
   120  	MaxIdleConns:          100,
   121  	IdleConnTimeout:       90 * time.Second,
   122  	TLSHandshakeTimeout:   10 * time.Second,
   123  	ExpectContinueTimeout: 1 * time.Second,
   124  	// We usually are dealing with 2 hosts (at most), split MaxIdleConns between them.
   125  	MaxIdleConnsPerHost: 50,
   126  }
   127  
   128  func makeOptions(opts ...Option) (*options, error) {
   129  	o := &options{
   130  		transport:        DefaultTransport,
   131  		platform:         defaultPlatform,
   132  		context:          context.Background(),
   133  		jobs:             defaultJobs,
   134  		pageSize:         defaultPageSize,
   135  		retryPredicate:   defaultRetryPredicate,
   136  		retryBackoff:     defaultRetryBackoff,
   137  		retryStatusCodes: defaultRetryStatusCodes,
   138  	}
   139  
   140  	for _, option := range opts {
   141  		if err := option(o); err != nil {
   142  			return nil, err
   143  		}
   144  	}
   145  
   146  	switch {
   147  	case o.auth != nil && o.keychain != nil:
   148  		// It is a better experience to explicitly tell a caller their auth is misconfigured
   149  		// than potentially fail silently when the correct auth is overridden by option misuse.
   150  		return nil, errors.New("provide an option for either authn.Authenticator or authn.Keychain, not both")
   151  	case o.auth == nil:
   152  		o.auth = authn.Anonymous
   153  	}
   154  
   155  	// transport.Wrapper is a signal that consumers are opt-ing into providing their own transport without any additional wrapping.
   156  	// This is to allow consumers full control over the transports logic, such as providing retry logic.
   157  	if _, ok := o.transport.(*transport.Wrapper); !ok {
   158  		// Wrap the transport in something that logs requests and responses.
   159  		// It's expensive to generate the dumps, so skip it if we're writing
   160  		// to nothing.
   161  		if logs.Enabled(logs.Debug) {
   162  			o.transport = transport.NewLogger(o.transport)
   163  		}
   164  
   165  		// Wrap the transport in something that can retry network flakes.
   166  		o.transport = transport.NewRetry(o.transport, transport.WithRetryPredicate(defaultRetryPredicate), transport.WithRetryStatusCodes(o.retryStatusCodes...))
   167  
   168  		// Wrap this last to prevent transport.New from double-wrapping.
   169  		if o.userAgent != "" {
   170  			o.transport = transport.NewUserAgent(o.transport, o.userAgent)
   171  		}
   172  	}
   173  
   174  	return o, nil
   175  }
   176  
   177  // WithTransport is a functional option for overriding the default transport
   178  // for remote operations.
   179  // If transport.Wrapper is provided, this signals that the consumer does *not* want any further wrapping to occur.
   180  // i.e. logging, retry and useragent
   181  //
   182  // The default transport is DefaultTransport.
   183  func WithTransport(t http.RoundTripper) Option {
   184  	return func(o *options) error {
   185  		o.transport = t
   186  		return nil
   187  	}
   188  }
   189  
   190  // WithAuth is a functional option for overriding the default authenticator
   191  // for remote operations.
   192  // It is an error to use both WithAuth and WithAuthFromKeychain in the same Option set.
   193  //
   194  // The default authenticator is authn.Anonymous.
   195  func WithAuth(auth authn.Authenticator) Option {
   196  	return func(o *options) error {
   197  		o.auth = auth
   198  		return nil
   199  	}
   200  }
   201  
   202  // WithAuthFromKeychain is a functional option for overriding the default
   203  // authenticator for remote operations, using an authn.Keychain to find
   204  // credentials.
   205  // It is an error to use both WithAuth and WithAuthFromKeychain in the same Option set.
   206  //
   207  // The default authenticator is authn.Anonymous.
   208  func WithAuthFromKeychain(keys authn.Keychain) Option {
   209  	return func(o *options) error {
   210  		o.keychain = keys
   211  		return nil
   212  	}
   213  }
   214  
   215  // WithPlatform is a functional option for overriding the default platform
   216  // that Image and Descriptor.Image use for resolving an index to an image.
   217  //
   218  // The default platform is amd64/linux.
   219  func WithPlatform(p v1.Platform) Option {
   220  	return func(o *options) error {
   221  		o.platform = p
   222  		return nil
   223  	}
   224  }
   225  
   226  // WithContext is a functional option for setting the context in http requests
   227  // performed by a given function. Note that this context is used for _all_
   228  // http requests, not just the initial volley. E.g., for remote.Image, the
   229  // context will be set on http requests generated by subsequent calls to
   230  // RawConfigFile() and even methods on layers returned by Layers().
   231  //
   232  // The default context is context.Background().
   233  func WithContext(ctx context.Context) Option {
   234  	return func(o *options) error {
   235  		o.context = ctx
   236  		return nil
   237  	}
   238  }
   239  
   240  // WithJobs is a functional option for setting the parallelism of remote
   241  // operations performed by a given function. Note that not all remote
   242  // operations support parallelism.
   243  //
   244  // The default value is 4.
   245  func WithJobs(jobs int) Option {
   246  	return func(o *options) error {
   247  		if jobs <= 0 {
   248  			return errors.New("jobs must be greater than zero")
   249  		}
   250  		o.jobs = jobs
   251  		return nil
   252  	}
   253  }
   254  
   255  // WithUserAgent adds the given string to the User-Agent header for any HTTP
   256  // requests. This header will also include "go-containerregistry/${version}".
   257  //
   258  // If you want to completely overwrite the User-Agent header, use WithTransport.
   259  func WithUserAgent(ua string) Option {
   260  	return func(o *options) error {
   261  		o.userAgent = ua
   262  		return nil
   263  	}
   264  }
   265  
   266  // WithNondistributable includes non-distributable (foreign) layers
   267  // when writing images, see:
   268  // https://github.com/opencontainers/image-spec/blob/master/layer.md#non-distributable-layers
   269  //
   270  // The default behaviour is to skip these layers
   271  func WithNondistributable(o *options) error {
   272  	o.allowNondistributableArtifacts = true
   273  	return nil
   274  }
   275  
   276  // WithProgress takes a channel that will receive progress updates as bytes are written.
   277  //
   278  // Sending updates to an unbuffered channel will block writes, so callers
   279  // should provide a buffered channel to avoid potential deadlocks.
   280  func WithProgress(updates chan<- v1.Update) Option {
   281  	return func(o *options) error {
   282  		o.progress = &progress{updates: updates}
   283  		o.progress.lastUpdate = &v1.Update{}
   284  		return nil
   285  	}
   286  }
   287  
   288  // WithPageSize sets the given size as the value of parameter 'n' in the request.
   289  //
   290  // To omit the `n` parameter entirely, use WithPageSize(0).
   291  // The default value is 1000.
   292  func WithPageSize(size int) Option {
   293  	return func(o *options) error {
   294  		o.pageSize = size
   295  		return nil
   296  	}
   297  }
   298  
   299  // WithRetryBackoff sets the httpBackoff for retry HTTP operations.
   300  func WithRetryBackoff(backoff Backoff) Option {
   301  	return func(o *options) error {
   302  		o.retryBackoff = backoff
   303  		return nil
   304  	}
   305  }
   306  
   307  // WithRetryPredicate sets the predicate for retry HTTP operations.
   308  func WithRetryPredicate(predicate retry.Predicate) Option {
   309  	return func(o *options) error {
   310  		o.retryPredicate = predicate
   311  		return nil
   312  	}
   313  }
   314  
   315  // WithRetryStatusCodes sets which http response codes will be retried.
   316  func WithRetryStatusCodes(codes ...int) Option {
   317  	return func(o *options) error {
   318  		o.retryStatusCodes = codes
   319  		return nil
   320  	}
   321  }
   322  
   323  // WithFilter sets the filter querystring for HTTP operations.
   324  func WithFilter(key string, value string) Option {
   325  	return func(o *options) error {
   326  		if o.filter == nil {
   327  			o.filter = map[string]string{}
   328  		}
   329  		o.filter[key] = value
   330  		return nil
   331  	}
   332  }
   333  
   334  // Reuse takes a Puller or Pusher and reuses it for remote interactions
   335  // rather than starting from a clean slate. For example, it will reuse token exchanges
   336  // when possible and avoid sending redundant HEAD requests.
   337  //
   338  // Reuse will take precedence over other options passed to most remote functions because
   339  // most options deal with setting up auth and transports, which Reuse intetionally skips.
   340  func Reuse[I *Puller | *Pusher](i I) Option {
   341  	return func(o *options) error {
   342  		if puller, ok := any(i).(*Puller); ok {
   343  			o.puller = puller
   344  		} else if pusher, ok := any(i).(*Pusher); ok {
   345  			o.pusher = pusher
   346  		}
   347  		return nil
   348  	}
   349  }
   350
View as plain text