descriptor.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  	"fmt"
    21  
    22  	"github.com/google/go-containerregistry/pkg/logs"
    23  	"github.com/google/go-containerregistry/pkg/name"
    24  	v1 "github.com/google/go-containerregistry/pkg/v1"
    25  	"github.com/google/go-containerregistry/pkg/v1/partial"
    26  	"github.com/google/go-containerregistry/pkg/v1/types"
    27  )
    28  
    29  var allManifestMediaTypes = append(append([]types.MediaType{
    30  	types.DockerManifestSchema1,
    31  	types.DockerManifestSchema1Signed,
    32  }, acceptableImageMediaTypes...), acceptableIndexMediaTypes...)
    33  
    34  // ErrSchema1 indicates that we received a schema1 manifest from the registry.
    35  // This library doesn't have plans to support this legacy image format:
    36  // https://github.com/google/go-containerregistry/issues/377
    37  var ErrSchema1 = errors.New("see https://github.com/google/go-containerregistry/issues/377")
    38  
    39  // newErrSchema1 returns an ErrSchema1 with the unexpected MediaType.
    40  func newErrSchema1(schema types.MediaType) error {
    41  	return fmt.Errorf("unsupported MediaType: %q, %w", schema, ErrSchema1)
    42  }
    43  
    44  // Descriptor provides access to metadata about remote artifact and accessors
    45  // for efficiently converting it into a v1.Image or v1.ImageIndex.
    46  type Descriptor struct {
    47  	fetcher fetcher
    48  	v1.Descriptor
    49  
    50  	ref      name.Reference
    51  	Manifest []byte
    52  	ctx      context.Context
    53  
    54  	// So we can share this implementation with Image.
    55  	platform v1.Platform
    56  }
    57  
    58  func (d *Descriptor) toDesc() v1.Descriptor {
    59  	return d.Descriptor
    60  }
    61  
    62  // RawManifest exists to satisfy the Taggable interface.
    63  func (d *Descriptor) RawManifest() ([]byte, error) {
    64  	return d.Manifest, nil
    65  }
    66  
    67  // Get returns a remote.Descriptor for the given reference. The response from
    68  // the registry is left un-interpreted, for the most part. This is useful for
    69  // querying what kind of artifact a reference represents.
    70  //
    71  // See Head if you don't need the response body.
    72  func Get(ref name.Reference, options ...Option) (*Descriptor, error) {
    73  	return get(ref, allManifestMediaTypes, options...)
    74  }
    75  
    76  // Head returns a v1.Descriptor for the given reference by issuing a HEAD
    77  // request.
    78  //
    79  // Note that the server response will not have a body, so any errors encountered
    80  // should be retried with Get to get more details.
    81  func Head(ref name.Reference, options ...Option) (*v1.Descriptor, error) {
    82  	o, err := makeOptions(options...)
    83  	if err != nil {
    84  		return nil, err
    85  	}
    86  
    87  	return newPuller(o).Head(o.context, ref)
    88  }
    89  
    90  // Handle options and fetch the manifest with the acceptable MediaTypes in the
    91  // Accept header.
    92  func get(ref name.Reference, acceptable []types.MediaType, options ...Option) (*Descriptor, error) {
    93  	o, err := makeOptions(options...)
    94  	if err != nil {
    95  		return nil, err
    96  	}
    97  	return newPuller(o).get(o.context, ref, acceptable, o.platform)
    98  }
    99  
   100  // Image converts the Descriptor into a v1.Image.
   101  //
   102  // If the fetched artifact is already an image, it will just return it.
   103  //
   104  // If the fetched artifact is an index, it will attempt to resolve the index to
   105  // a child image with the appropriate platform.
   106  //
   107  // See WithPlatform to set the desired platform.
   108  func (d *Descriptor) Image() (v1.Image, error) {
   109  	switch d.MediaType {
   110  	case types.DockerManifestSchema1, types.DockerManifestSchema1Signed:
   111  		// We don't care to support schema 1 images:
   112  		// https://github.com/google/go-containerregistry/issues/377
   113  		return nil, newErrSchema1(d.MediaType)
   114  	case types.OCIImageIndex, types.DockerManifestList:
   115  		// We want an image but the registry has an index, resolve it to an image.
   116  		return d.remoteIndex().imageByPlatform(d.platform)
   117  	case types.OCIManifestSchema1, types.DockerManifestSchema2:
   118  		// These are expected. Enumerated here to allow a default case.
   119  	default:
   120  		// We could just return an error here, but some registries (e.g. static
   121  		// registries) don't set the Content-Type headers correctly, so instead...
   122  		logs.Warn.Printf("Unexpected media type for Image(): %s", d.MediaType)
   123  	}
   124  
   125  	// Wrap the v1.Layers returned by this v1.Image in a hint for downstream
   126  	// remote.Write calls to facilitate cross-repo "mounting".
   127  	imgCore, err := partial.CompressedToImage(d.remoteImage())
   128  	if err != nil {
   129  		return nil, err
   130  	}
   131  	return &mountableImage{
   132  		Image:     imgCore,
   133  		Reference: d.ref,
   134  	}, nil
   135  }
   136  
   137  // Schema1 converts the Descriptor into a v1.Image for v2 schema 1 media types.
   138  //
   139  // The v1.Image returned by this method does not implement the entire interface because it would be inefficient.
   140  // This exists mostly to make it easier to copy schema 1 images around or look at their filesystems.
   141  // This is separate from Image() to avoid a backward incompatible change for callers expecting ErrSchema1.
   142  func (d *Descriptor) Schema1() (v1.Image, error) {
   143  	i := &schema1{
   144  		ref:        d.ref,
   145  		fetcher:    d.fetcher,
   146  		ctx:        d.ctx,
   147  		manifest:   d.Manifest,
   148  		mediaType:  d.MediaType,
   149  		descriptor: &d.Descriptor,
   150  	}
   151  
   152  	return &mountableImage{
   153  		Image:     i,
   154  		Reference: d.ref,
   155  	}, nil
   156  }
   157  
   158  // ImageIndex converts the Descriptor into a v1.ImageIndex.
   159  func (d *Descriptor) ImageIndex() (v1.ImageIndex, error) {
   160  	switch d.MediaType {
   161  	case types.DockerManifestSchema1, types.DockerManifestSchema1Signed:
   162  		// We don't care to support schema 1 images:
   163  		// https://github.com/google/go-containerregistry/issues/377
   164  		return nil, newErrSchema1(d.MediaType)
   165  	case types.OCIManifestSchema1, types.DockerManifestSchema2:
   166  		// We want an index but the registry has an image, nothing we can do.
   167  		return nil, fmt.Errorf("unexpected media type for ImageIndex(): %s; call Image() instead", d.MediaType)
   168  	case types.OCIImageIndex, types.DockerManifestList:
   169  		// These are expected.
   170  	default:
   171  		// We could just return an error here, but some registries (e.g. static
   172  		// registries) don't set the Content-Type headers correctly, so instead...
   173  		logs.Warn.Printf("Unexpected media type for ImageIndex(): %s", d.MediaType)
   174  	}
   175  	return d.remoteIndex(), nil
   176  }
   177  
   178  func (d *Descriptor) remoteImage() *remoteImage {
   179  	return &remoteImage{
   180  		ref:        d.ref,
   181  		ctx:        d.ctx,
   182  		fetcher:    d.fetcher,
   183  		manifest:   d.Manifest,
   184  		mediaType:  d.MediaType,
   185  		descriptor: &d.Descriptor,
   186  	}
   187  }
   188  
   189  func (d *Descriptor) remoteIndex() *remoteIndex {
   190  	return &remoteIndex{
   191  		ref:        d.ref,
   192  		ctx:        d.ctx,
   193  		fetcher:    d.fetcher,
   194  		manifest:   d.Manifest,
   195  		mediaType:  d.MediaType,
   196  		descriptor: &d.Descriptor,
   197  	}
   198  }
   199
View as plain text