package transport

import "github.com/google/go-containerregistry/pkg/v1/remote/transport"

Package transport provides facilities for setting up an authenticated http.RoundTripper given an Authenticator and base RoundTripper. See transport.New for more information.

Index

Constants 

const (
	PullScope string = "pull"
	PushScope string = "push,pull"
	// For now DELETE is PUSH, which is the read/write ACL.
	DeleteScope  string = PushScope
	CatalogScope string = "catalog"
)

Scopes suitable to qualify each Repository

Variables 

var (
	// Version can be set via:
	// -ldflags="-X 'github.com/google/go-containerregistry/pkg/v1/remote/transport.Version=$TAG'"
	Version string
)

Functions

func CheckError 

func CheckError(resp *http.Response, codes ...int) error

CheckError returns a structured error if the response status is not in codes.

func FromToken 

func FromToken(reg name.Registry, auth authn.Authenticator, t http.RoundTripper, pr *Challenge, tok *Token) (http.RoundTripper, error)

FromToken returns a transport given a Challenge + Token.

func New 

func New(reg name.Registry, auth authn.Authenticator, t http.RoundTripper, scopes []string) (http.RoundTripper, error)

New returns a new RoundTripper based on the provided RoundTripper that has been setup to authenticate with the remote registry "reg", in the capacity laid out by the specified scopes.

Deprecated: Use NewWithContext.

func NewLogger 

func NewLogger(inner http.RoundTripper) http.RoundTripper

NewLogger returns a transport that logs requests and responses to github.com/google/go-containerregistry/pkg/logs.Debug.

func NewRetry 

func NewRetry(inner http.RoundTripper, opts ...Option) http.RoundTripper

NewRetry returns a transport that retries errors.

func NewUserAgent 

func NewUserAgent(inner http.RoundTripper, ua string) http.RoundTripper

NewUserAgent returns an http.Roundtripper that sets the user agent to The provided string plus additional go-containerregistry information, e.g. if provided "crane/v0.1.4" and this modules was built at v0.1.4:

User-Agent: crane/v0.1.4 go-containerregistry/v0.1.4

func NewWithContext 

func NewWithContext(ctx context.Context, reg name.Registry, auth authn.Authenticator, t http.RoundTripper, scopes []string) (http.RoundTripper, error)

NewWithContext returns a new RoundTripper based on the provided RoundTripper that has been set up to authenticate with the remote registry "reg", in the capacity laid out by the specified scopes. In case the RoundTripper is already of the type Wrapper it assumes authentication was already done prior to this call, so it just returns the provided RoundTripper without further action

Types

type Backoff 

type Backoff = retry.Backoff

Backoff is an alias of retry.Backoff to expose this configuration option to consumers of this lib

type Challenge 

type Challenge struct {
	Scheme string

	// Following the challenge there are often key/value pairs
	// e.g. Bearer service="gcr.io",realm="https://auth.gcr.io/v36/tokenz"
	Parameters map[string]string

	// Whether we had to use http to complete the Ping.
	Insecure bool
}

func Ping 

func Ping(ctx context.Context, reg name.Registry, t http.RoundTripper) (*Challenge, error)

Ping does a GET /v2/ against the registry and returns the response.

type Diagnostic 

type Diagnostic struct {
	Code    ErrorCode `json:"code"`
	Message string    `json:"message,omitempty"`
	Detail  any       `json:"detail,omitempty"`
}

Diagnostic represents a single error returned by a Docker registry interaction.

func (Diagnostic) String 

func (d Diagnostic) String() string

String stringifies the Diagnostic in the form: $Code: $Message[; $Detail]

type Error 

type Error struct {
	Errors []Diagnostic `json:"errors,omitempty"`
	// The http status code returned.
	StatusCode int
	// The request that failed.
	Request *http.Request
	// contains filtered or unexported fields
}

Error implements error to support the following error specification: https://github.com/docker/distribution/blob/master/docs/spec/api.md#errors

func (*Error) Error 

func (e *Error) Error() string

Error implements error

func (*Error) Temporary 

func (e *Error) Temporary() bool

Temporary returns whether the request that preceded the error is temporary.

type ErrorCode 

type ErrorCode string

ErrorCode is an enumeration of supported error codes. 

const (
	BlobUnknownErrorCode         ErrorCode = "BLOB_UNKNOWN"
	BlobUploadInvalidErrorCode   ErrorCode = "BLOB_UPLOAD_INVALID"
	BlobUploadUnknownErrorCode   ErrorCode = "BLOB_UPLOAD_UNKNOWN"
	DigestInvalidErrorCode       ErrorCode = "DIGEST_INVALID"
	ManifestBlobUnknownErrorCode ErrorCode = "MANIFEST_BLOB_UNKNOWN"
	ManifestInvalidErrorCode     ErrorCode = "MANIFEST_INVALID"
	ManifestUnknownErrorCode     ErrorCode = "MANIFEST_UNKNOWN"
	ManifestUnverifiedErrorCode  ErrorCode = "MANIFEST_UNVERIFIED"
	NameInvalidErrorCode         ErrorCode = "NAME_INVALID"
	NameUnknownErrorCode         ErrorCode = "NAME_UNKNOWN"
	SizeInvalidErrorCode         ErrorCode = "SIZE_INVALID"
	TagInvalidErrorCode          ErrorCode = "TAG_INVALID"
	UnauthorizedErrorCode        ErrorCode = "UNAUTHORIZED"
	DeniedErrorCode              ErrorCode = "DENIED"
	UnsupportedErrorCode         ErrorCode = "UNSUPPORTED"
	TooManyRequestsErrorCode     ErrorCode = "TOOMANYREQUESTS"
	UnknownErrorCode             ErrorCode = "UNKNOWN"

	// This isn't defined by either docker or OCI spec, but is defined by docker/distribution:
	// https://github.com/distribution/distribution/blob/6a977a5a754baa213041443f841705888107362a/registry/api/errcode/register.go#L60
	UnavailableErrorCode ErrorCode = "UNAVAILABLE"
)

The set of error conditions a registry may return: https://github.com/docker/distribution/blob/master/docs/spec/api.md#errors-2

type Option 

type Option func(*options)

Option is a functional option for retryTransport.

func WithRetryBackoff 

func WithRetryBackoff(backoff Backoff) Option

WithRetryBackoff sets the backoff for retry operations.

func WithRetryPredicate 

func WithRetryPredicate(predicate func(error) bool) Option

WithRetryPredicate sets the predicate for retry operations.

func WithRetryStatusCodes 

func WithRetryStatusCodes(codes ...int) Option

WithRetryStatusCodes sets which http response codes will be retried.

type Token 

type Token struct {
	Token        string `json:"token"`
	AccessToken  string `json:"access_token,omitempty"`
	RefreshToken string `json:"refresh_token"`
	ExpiresIn    int    `json:"expires_in"`
}

func Exchange 

func Exchange(ctx context.Context, reg name.Registry, auth authn.Authenticator, t http.RoundTripper, scopes []string, pr *Challenge) (*Token, error)

Exchange requests a registry Token with the given scopes.

type Wrapper 

type Wrapper struct {
	// contains filtered or unexported fields
}

Wrapper results in *not* wrapping supplied transport with additional logic such as retries, useragent and debug logging Consumers are opt-ing into providing their own transport without any additional wrapping.

func (*Wrapper) RoundTrip 

func (w *Wrapper) RoundTrip(in *http.Request) (*http.Response, error)

RoundTrip delegates to the inner RoundTripper

Source Files

basic.go bearer.go doc.go error.go logger.go ping.go retry.go schemer.go scope.go transport.go useragent.go

Version
v0.20.5 (latest)
Published
May 21, 2025
Platform
linux/amd64
Imports
20 packages
Last checked
3 hours ago –

Tools for package owners.