Registry Interface

[shizhMSFT]

Resolves #58

[Wwwsylvia]

LGTM

[deitch]

@shizhMSFT I am trying to wrap my head around it. I have a few questions, although I think I get it.

• registry as top-level: Why is the registry/ package at the top-level and not part of content? I think you are stating that there are two (maybe more) high-level interfaces: Copy() which copies things from Target A to Target B; and registry.Registry which provides for interactions with a registry. Of course, I can use a registry.Registry to get a registry.Repository, which satisfies a Target, which is usable with Copy(). Is that it? If so, I think having the docs state explicitly what the key to-level entry points to oras are. I was thinking entirely in Copy() terms until I got the above, and then it all seemed to make sense (if I got it right, that is).
• content and Target. I understand why a registry.Repository would fulfill Target, so it can be used in Copy(). What are the other content.* interfaces that it implements, and why does it need them?

[shizhMSFT]

registry.Registry which provides for interactions with a registry. Of course, I can use a registry.Registry to get a registry.Repository, which satisfies a Target, which is usable with Copy(). Is that it?

@deitch Yes, exactly.

Behind the scene, oras and oras-go are envolving into a full registry client in addition to its content Copy() functionality. Since it is a full registry client, it would be better to promote the content/registry package to the top level (i.e. registry as it is in the PR). @jdolitsky @sajayantony Any votes on the package path?

What are the other content.* interfaces that it implements, and why does it need them?

Besides oras.Target, the registry.Repository interface includes content.Deleter so that it can delete a blob or a manifest since it is a full registry client. Note that both oras.Target and BlobStore have content.Storage and content.Resolver.
For other interfaces like TagPusher, Blobs(), Manifests(), Tags(), I've documented them and they are there for the functionalities of a registry client.

[shizhMSFT]

To get the full picture, you may take a look at my current working branch, which I will make a PR and send it out after this PR is merged.

Here are some example usages (note: I am still implementing the auth):

src, err := distribution.NewRepository("localhost:5000/hello-world")
check(err)
src.PlainHTTP = true

dst, err := distribution.NewRepository("localhost:5001/hello")
check(err)
dst.PlainHTTP = true

desc, err := oras.Copy(ctx, src, "latest", dst, "")
check(err)

src, err := distribution.NewRepository("mcr.microsoft.com/hello-world:latest")
check(err)

dst := memory.New()

_, err = oras.Copy(ctx, src, src.Reference.String(), dst, "")
check(err)

reg, err := distribution.NewRegistry("localhost:5000")
check(err)
reg.PlainHTTP = true
catalog, err := registry.Repositories(ctx, reg)
check(err)
fmt.Println(catalog)

repo, err := reg.Repository(ctx, "alpine")
check(err)
tags, err := registry.Tags(ctx, repo)
check(err)
fmt.Println(tags)

where the full package name of distribution is oras.land/oras-go/v2/registry/distribution.

[deitch]

Thanks for the explanation @shizhMSFT ; makes sense.

I do think we need clearer docs explaining what the high level interfaces are (primarily two: Copy and Registry`), but that needs to be fixed here and can come later.

[shizhMSFT]

We definitely will document the library in the oras-www repo.