1# `partial`
2
3[](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/partial)
4
5## Partial Implementations
6
7There are roughly two kinds of image representations: compressed and uncompressed.
8
9The implementations for these kinds of images are almost identical, with the only
10major difference being how blobs (config and layers) are fetched. This common
11code lives in this package, where you provide a _partial_ implementation of a
12compressed or uncompressed image, and you get back a full `v1.Image` implementation.
13
14### Examples
15
16In a registry, blobs are compressed, so it's easiest to implement a `v1.Image` in terms
17of compressed layers. `remote.remoteImage` does this by implementing `CompressedImageCore`:
18
19```go
20type CompressedImageCore interface {
21 RawConfigFile() ([]byte, error)
22 MediaType() (types.MediaType, error)
23 RawManifest() ([]byte, error)
24 LayerByDigest(v1.Hash) (CompressedLayer, error)
25}
26```
27
28In a tarball, blobs are (often) uncompressed, so it's easiest to implement a `v1.Image` in terms
29of uncompressed layers. `tarball.uncompressedImage` does this by implementing `UncompressedImageCore`:
30
31```go
32type UncompressedImageCore interface {
33 RawConfigFile() ([]byte, error)
34 MediaType() (types.MediaType, error)
35 LayerByDiffID(v1.Hash) (UncompressedLayer, error)
36}
37```
38
39## Optional Methods
40
41Where possible, we access some information via optional methods as an optimization.
42
43### [`partial.Descriptor`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/partial#Descriptor)
44
45There are some properties of a [`Descriptor`](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#properties) that aren't derivable from just image data:
46
47* `MediaType`
48* `Platform`
49* `URLs`
50* `Annotations`
51
52For example, in a `tarball.Image`, there is a `LayerSources` field that contains
53an entire layer descriptor with `URLs` information for foreign layers. This
54information can be passed through to callers by implementing this optional
55`Descriptor` method.
56
57See [`#654`](https://github.com/google/go-containerregistry/pull/654).
58
59### [`partial.UncompressedSize`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/partial#UncompressedSize)
60
61Usually, you don't need to know the uncompressed size of a layer, since that
62information isn't stored in a config file (just he sha256 is needed); however,
63there are cases where it is very helpful to know the layer size, e.g. when
64writing the uncompressed layer into a tarball.
65
66See [`#655`](https://github.com/google/go-containerregistry/pull/655).
67
68### [`partial.Exists`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/partial#Exists)
69
70We generally don't care about the existence of something as granular as a
71layer, and would rather ensure all the invariants of an image are upheld via
72the `validate` package. However, there are situations where we want to do a
73quick smoke test to ensure that the underlying storage engine hasn't been
74corrupted by something e.g. deleting files or blobs. Thus, we've exposed an
75optional `Exists` method that does an existence check without actually reading
76any bytes.
77
78The `remote` package implements this via `HEAD` requests.
79
80The `layout` package implements this via `os.Stat`.
81
82See [`#838`](https://github.com/google/go-containerregistry/pull/838).
View as plain text