Add examples for repository push, pull, resolve and tags #119

qweeah · 2022-03-18T09:14:17Z

This PR works for item #60 and adds examples for:
Push & pull blobs
Tag a image
Resolve the tag
List tags in a repository

registry/remote/example_test.go

Wwwsylvia · 2022-04-02T10:14:46Z

We will need examples for FetchReference once #124 gets merged.

content/example_test.go

registry/remote/example_test.go

shizhMSFT · 2022-04-02T12:02:22Z

registry/remote/example_test.go

+	if err != nil {
+		panic(err) // Handle error
+	}
+	// If you want to play with your local registry, try to override


nit: Try using objective wording and try to avoid words like you, he, she, I, we.

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

* pack * fix pack * add pack test Signed-off-by: Lixia (Sylvia) Lei <lixia_lei@outlook.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Signed-off-by: Sylvia Lei <lixlei@microsoft.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Signed-off-by: Sajay Antony <sajaya@microsoft.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

…#117) Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Signed-off-by: Lixia (Sylvia) Lei <lixia_lei@outlook.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

* pack * fix pack * add pack test Signed-off-by: Lixia (Sylvia) Lei <lixia_lei@outlook.com>

Signed-off-by: Sajay Antony <sajaya@microsoft.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

…#117) Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Wwwsylvia · 2022-04-07T07:50:09Z

In the example, I pulled a tagged layer from the registry

You actually pulled a manifest.
Ah I see what's not right, you used the same digest for mocking /v2/<repository>/manifests/<reference> API and /v2/<repository>/blobs/<reference> API (https://github.com/qweeah/oras-go/blob/repository-example/registry/remote/example_test.go#L77-L82), so you didn't notice which API you were accessing. You may refer to TestRepository_Fetch for the mocks.

I think manifest is also a blob with specific media type, which should also be the common sense of oras-go user (correct me if I am wrong). Thus we don't need to clarify that, at least not in the example.

Yeah but when querying remote registries, manifests and blobs go through different API endpoints. Just that functions like Repository.Fetch() automatically choose endpoints based on the media type.
For users familiar with Docker V2 API, they may want to know how the oras-go functions correspond to the V2 APIs? (Just a thought)

User can also resolve the descriptor of a (layer or config) blob by Repository.Resolve()

No they can't.
Repository.Resolve() calls Manifests().Resolve() behind the scenes, which queries the /v2/<repository>/manifests/<reference> API (See https://github.com/oras-project/oras-go/blob/main/registry/remote/repository.go#L760). So it only resolves manifests.

// Resolve resolves a reference to a manifest descriptor.
// See also `ManifestMediaTypes`.
func (r *Repository) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error) {
	return r.Manifests().Resolve(ctx, reference)
}

qweeah · 2022-04-07T09:20:04Z

In the example, I pulled a tagged layer from the registry

You actually pulled a manifest. Ah I see what's not right, you used the same digest for mocking /v2/<repository>/manifests/<reference> API and /v2/<repository>/blobs/<reference> API (https://github.com/qweeah/oras-go/blob/repository-example/registry/remote/example_test.go#L77-L82), so you didn't notice which API you were accessing. You may refer to TestRepository_Fetch for the mocks.

I think manifest is also a blob with specific media type, which should also be the common sense of oras-go user (correct me if I am wrong). Thus we don't need to clarify that, at least not in the example.

Yeah but when querying remote registries, manifests and blobs go through different API endpoints. Just that functions like Repository.Fetch() automatically choose endpoints based on the media type. For users familiar with Docker V2 API, they may want to know how the oras-go functions correspond to the V2 APIs? (Just a thought)

User can also resolve the descriptor of a (layer or config) blob by Repository.Resolve()

No they can't. Repository.Resolve() calls Manifests().Resolve() behind the scenes, which queries the /v2/<repository>/manifests/<reference> API (See https://github.com/oras-project/oras-go/blob/main/registry/remote/repository.go#L760). So it only resolves manifests.
// Resolve resolves a reference to a manifest descriptor.
// See also `ManifestMediaTypes`.
func (r *Repository) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error) {
	return r.Manifests().Resolve(ctx, reference)
}

Yes you are right. Looks like I mixed Repository.Resolve with BlobStore.Resolve. I will separate blob pull and manifest pull.

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

qweeah · 2022-04-08T18:40:37Z

@Wwwsylvia I separated examples for manifest and layer fetch and added new examples for manifes FetchReference. Please take a review when you got time, thanks

registry/remote/example_test.go

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

registry/remote/example_test.go

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

registry/remote/example_test.go

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Wwwsylvia

LGTM

registry/remote/example_test.go

shizhMSFT · 2022-04-15T05:19:40Z

registry/remote/example_test.go

+	pulledBlob, err := io.ReadAll(rc)
+	if err != nil {
+		panic(err)
+	}
+	// verify the fetched content
+	if descriptor.Digest != ocidigest.FromBytes(pulledBlob) || descriptor.Size != int64(len(pulledBlob)) {
+		panic(err)
+	}


Looks like we have lots of duplicated code like this.

@Wwwsylvia What do you think if we promote internal/ioutil.ReadAll() to the content package?

That would be useful.

Issue created: #128

registry/remote/example_test.go

shizhMSFT · 2022-04-15T05:30:32Z

registry/remote/example_test.go

+	descriptor, err := repo.Resolve(ctx, digest)
+	if err != nil {
+		panic(err)
+	}
+	tag := "latest"
+	err = repo.Tag(ctx, descriptor, tag)
+	if err != nil {
+		panic(err)
+	}


@Wwwsylvia Resolve and Tag will have 3 requests in total. We probably need a more efficient one by having a generic Tag() function by leveraging FetchReference() and PushReference().

Make sense.
Like func (r *Repository) ReTag(ctx context.Context, srcRef, destRef string) error? Need to figure out a new function name.

How about func Tag(ctx context.Context, repo Repository, srcRef, dstRef string) error in package registry?

@qweeah has created an issue for this: #120

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

shizhMSFT

LGTM

shizhMSFT requested review from shizhMSFT and Wwwsylvia March 21, 2022 06:12

qweeah marked this pull request as draft March 25, 2022 01:53

qweeah marked this pull request as ready for review March 25, 2022 03:27

qweeah force-pushed the repository-example branch from 70c27db to c203798 Compare March 28, 2022 04:57

sajayantony reviewed Mar 29, 2022

View reviewed changes

registry/remote/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Show resolved Hide resolved

qweeah force-pushed the repository-example branch from 05270e8 to dc5ef24 Compare March 30, 2022 11:39

shizhMSFT requested changes Apr 1, 2022

View reviewed changes

registry/remote/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Outdated Show resolved Hide resolved

shizhMSFT reviewed Apr 2, 2022

View reviewed changes

content/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Outdated Show resolved Hide resolved

shizhMSFT reviewed Apr 2, 2022

View reviewed changes

registry/remote/example_test.go Outdated Show resolved Hide resolved

shizhMSFT reviewed Apr 2, 2022

View reviewed changes

qweeah and others added 18 commits April 6, 2022 13:08

Examples for repository push, pull, resolve

2d34ca1

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Add tag example

f6ca9bd

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Add oras.Pack (oras-project#114)

9c9a50a

* pack * fix pack * add pack test Signed-off-by: Lixia (Sylvia) Lei <lixia_lei@outlook.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

fix memory graph (oras-project#115)

57e2ce6

Signed-off-by: Sylvia Lei <lixlei@microsoft.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Fix godoc output and add package overviews (oras-project#116)

66493ac

Signed-off-by: Sajay Antony <sajaya@microsoft.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Change package name & use TestMain

b5fc5c7

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Refactor examples for repository

d2f47ee

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Code clean

e801665

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Add example for listing repositories in registry target (oras-project…

546f20c

…#117) Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Merge registry TestMain in

857e364

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Merge examples into one file for remote package

27339f7

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Handle push response

275e953

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

fix OCI root (oras-project#125)

fbd2ae6

Signed-off-by: Lixia (Sylvia) Lei <lixia_lei@outlook.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Resolve reabase error

0956267

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Add oras.Pack (oras-project#114)

bdd98cc

* pack * fix pack * add pack test Signed-off-by: Lixia (Sylvia) Lei <lixia_lei@outlook.com>

Fix godoc output and add package overviews (oras-project#116)

e81f894

Signed-off-by: Sajay Antony <sajaya@microsoft.com> Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Add example for listing repositories in registry target (oras-project…

a20c6d2

…#117) Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Remove old examples

e3340b3

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Add examples for fetchReference and layer fetch

155ea0a

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

qweeah requested review from Wwwsylvia and shizhMSFT April 8, 2022 18:40

Merge remote-tracking branch 'origin_src/main' into repository-example

7516c28

Wwwsylvia reviewed Apr 11, 2022

View reviewed changes

registry/remote/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Outdated Show resolved Hide resolved

qweeah added 4 commits April 11, 2022 23:54

Clean up mocking code

bebcceb

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Add comment

b8d5d67

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Use blob resolve descriptor

e484029

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Comment clean

2a3c56b

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

qweeah requested a review from Wwwsylvia April 11, 2022 16:21

sajayantony reviewed Apr 12, 2022

View reviewed changes

Code clean

b19e08f

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

qweeah force-pushed the repository-example branch from b3e3769 to b19e08f Compare April 12, 2022 04:22

qweeah added 2 commits April 12, 2022 12:25

Code clean

8c50837

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Rewording comment

e8d59b8

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Wwwsylvia reviewed Apr 13, 2022

View reviewed changes

registry/remote/example_test.go Outdated Show resolved Hide resolved

registry/remote/example_test.go Show resolved Hide resolved

registry/remote/example_test.go Outdated Show resolved Hide resolved

qweeah added 3 commits April 13, 2022 22:40

Remove unnecessary comment

31ef5f9

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Add a scenario example for pushing a OCI image

8fb3155

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Code clean

1f9926b

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Wwwsylvia reviewed Apr 14, 2022

View reviewed changes

sajayantony approved these changes Apr 14, 2022

View reviewed changes

shizhMSFT reviewed Apr 15, 2022

View reviewed changes

qweeah added 3 commits April 15, 2022 13:51

Code clean

8eb6374

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Code clean

7936d53

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

Improve readability

decea2d

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

shizhMSFT approved these changes Apr 15, 2022

View reviewed changes

shizhMSFT merged commit c34895e into oras-project:main Apr 15, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add examples for repository push, pull, resolve and tags #119

Add examples for repository push, pull, resolve and tags #119

qweeah commented Mar 18, 2022 •

edited

Wwwsylvia commented Apr 2, 2022

shizhMSFT Apr 2, 2022

Wwwsylvia commented Apr 7, 2022 •

edited

qweeah commented Apr 7, 2022

qweeah commented Apr 8, 2022

Wwwsylvia left a comment

shizhMSFT Apr 15, 2022

Wwwsylvia Apr 15, 2022

Wwwsylvia Apr 15, 2022

shizhMSFT Apr 15, 2022

Wwwsylvia Apr 15, 2022

shizhMSFT Apr 15, 2022

Wwwsylvia Apr 15, 2022

Wwwsylvia Apr 15, 2022

shizhMSFT left a comment

Add examples for repository push, pull, resolve and tags #119

Add examples for repository push, pull, resolve and tags #119

Conversation

qweeah commented Mar 18, 2022 • edited

Wwwsylvia commented Apr 2, 2022

Choose a reason for hiding this comment

Wwwsylvia commented Apr 7, 2022 • edited

qweeah commented Apr 7, 2022

qweeah commented Apr 8, 2022

Wwwsylvia left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shizhMSFT left a comment

Choose a reason for hiding this comment

qweeah commented Mar 18, 2022 •

edited

Wwwsylvia commented Apr 7, 2022 •

edited