@wking number of components have no relevance here. The specification does not define anything about the path components. The backwards incompatibility comes from existing clients and servers. If a client is upgraded and now starts requesting localhost:5000/docker.io/library/ubuntu, the registry would have to be configured to treat docker.io as the same as previous requests it had seen. If it was an older registry, then it would just not understand the request, forcing the client to resend the request without docker.io. This sort of feature probing is a huge pain to implement for clients and this kind of configuration is really messy on the server. Using headers or query parameters can be safely ignored by older registries or omitted by older clients.

just like mirror-proxy function, it not spec scope in my mind.

There hasn't been much talk about this issue. Is this something we want to put on the agenda for Wednesday's call or can we push this to a later release?

I am going to open up a PR for it this week. We can discuss the design further there. I think this is important to properly implement the mirroring use case in a less opinionated manner (currently a mirror can only mirror a single upstream registry).

How about implementing a /v2/mirror/<repo> or /v2/<repo>/mirror endpoint and have the client use the Host header to let the registry know where to pull from?

Mirrors should be mostly transparent to the client, kind of like setting an HTTP proxy. Also the issue with the current situation is the repository name used by registries does not contain the host name which could lead to namespace collision in the registry implementation in the mirroring case. Using the HOST header in this case would not give enough indication of what the upstream HOST is, only the HOST for the mirror. HTTP proxying already covers the case where HOST does not need to point to the mirror, but this doesn't solve the case of having a single proxy/cache that can be used for multiple upstream registries.

I am working on a PR for this now. I will add a section under Use Cases for this which will describe how it is used, please comment on the design. The PR will update the individual requests.

Mirroring and Proxy Caching

Company X sets up an internal registry which is capable of storing local copies of images from any upstream registry.
Registry clients are configured to send all requests to retrieve registry data to the internal registry.
The clients attaches the OCI-Repository-Authority HTTP header to every registry request indicating the original registry host name.
The original registry host name is the authority for the given repository and used by the internal registry to fetch content and authentication parameters.

I think X-Proxy-Registry or OCI-Proxy-Registry is cleaner. When I think of authority, I think TLS certificates :P

Also, is it possible for clients to use separate creds for the local and authority?

Using the term "authority" here because a proxy is really required to delegate authority over content and access to that content to somewhere else. Whether it does that delegation by proxying is an implementation detail by the registry, same as how it constructs any proxy requests.

One thing to consider though is the use of an HTTP header vs a query parameter. A query parameter gives better cacheability in cases where there could be an even less sophisticated HTTP cache in between. A query parameter would prevent identical requests returning different content based solely on a non-standard HTTP header. In that cases we would have something like /v2/dmcgowan/myrepo/manifests/latest?authority=docker.io as the path. This is slightly more visible for registries which would not implement this though, however it may be a better solution. Note this query parameter would only show up when the client knows it is going through a mirror, because the HTTP Host header does not match the intended authority.

Yes I think a query parameter is better, otherwise for caching you need to set vary-by on a nonstandard header.

@justincormack my plan here to PoC it in containerd then open a PR for the spec here. I am not sure we have used a consistent naming scheme for what we call this, in containerd we usually call this part the namespace. Sometimes it is referred to as domain, registry, or host.

I think this is a good approach and the first step in separating registry location from the "authority". The eventual goal should be to encode the authority in the image name, but this will allow for cases where it is not.

Do registries currently ignore this parameter?