Skip to content

Permit HTTP redirects globally and add RFC references #607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tianon wants to merge 1 commit into
base: main
Choose a base branch
from
+16 −10
Open

Permit HTTP redirects globally and add RFC references #607

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Several terms are used frequently in this document and warrant basic definitions

### Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).

## Use Cases

Expand Down Expand Up @@ -165,7 +165,7 @@ The registry SHOULD NOT include parameters on the `Content-Type` header.
The client SHOULD ignore parameters on the `Content-Type` header.
The `Content-Type` header SHOULD match what the client [pushed as the manifest's `Content-Type`](#pushing-manifests).
If the manifest has a `mediaType` field, clients SHOULD reject unless the `mediaType` field's value matches the type specified by the `Content-Type` header.
For more information on the use of `Accept` headers and content negotiation, please see [Content Negotiation](./content-negotiation.md) and [RFC7231](https://www.rfc-editor.org/rfc/rfc7231#section-3.1.1.1).
For more information on the use of `Accept` headers and content negotiation, please see [Content Negotiation](./content-negotiation.md) and [RFC 7231 (section 3.1.1.1)](https://www.rfc-editor.org/rfc/rfc7231#section-3.1.1.1).

A GET request to an existing manifest URL MUST provide the expected manifest, with a response code that MUST be `200 OK`.
A successful response MUST contain the digest of the uploaded blob in the header `Docker-Content-Digest`.
Expand Down Expand Up @@ -193,7 +193,7 @@ Clients SHOULD verify that the response body matches the requested digest.

If the blob is not found in the repository, the response code MUST be `404 Not Found`.

A registry SHOULD support the `Range` request header in accordance with [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-range-requests).
A registry SHOULD support the `Range` request header in accordance with [RFC 9110 (section 14)](https://www.rfc-editor.org/rfc/rfc9110#section-14).

#### Checking if content exists in the registry

Expand Down Expand Up @@ -256,7 +256,7 @@ The `<location>` does not necessarily need to be provided by the registry itself
In fact, offloading to another server can be a [better strategy](https://www.backblaze.com/blog/design-thinking-b2-apis-the-hidden-costs-of-s3-compatibility/).

Optionally, the location MAY be absolute (containing the protocol and/or hostname), or it MAY be relative (containing just the URL path).
For more information, see [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.2).
For more information, see [RFC 7231 (section 7.1.2)](https://www.rfc-editor.org/rfc/rfc7231#section-7.1.2).

Once the `<location>` has been obtained, perform the upload proper by making a `PUT` request to the following URL path, and with the following headers and body:

Expand Down Expand Up @@ -472,7 +472,7 @@ This indicates that the upload session has begun and that the client MAY proceed
To push a manifest, perform a `PUT` request to a path in the following format, and with the following headers and body: `/v2/<name>/manifests/<reference>` <sup>[end-7](#endpoints)</sup>

Clients SHOULD set the `Content-Type` header to the type of the manifest being pushed.
The client SHOULD NOT include parameters on the `Content-Type` header (see [RFC7231](https://www.rfc-editor.org/rfc/rfc7231#section-3.1.1.1)).
The client SHOULD NOT include parameters on the `Content-Type` header (see [RFC 7231 (section 3.1.1.1)](https://www.rfc-editor.org/rfc/rfc7231#section-3.1.1.1)).
The registry SHOULD ignore parameters on the `Content-Type` header.
All manifests SHOULD include a `mediaType` field declaring the type of the manifest being pushed.
If a manifest includes a `mediaType` field, clients MUST set the `Content-Type` header to the value specified by the `mediaType` field.
Expand Down Expand Up @@ -509,7 +509,7 @@ If a registry supports this, it:

1. SHOULD support pushing at least 10 tags per request.
1. MAY return a `414 Request-URI Too Long` status if too many tags are included in the request.
1. MUST include an `OCI-Tag` response header, in accordance with [RFC 9110 (section 5)](https://www.rfc-editor.org/rfc/rfc9110#name-fields) semantics, for each accepted tag.
1. MUST include an `OCI-Tag` response header, in accordance with [RFC 9110 (section 5)](https://www.rfc-editor.org/rfc/rfc9110#section-5) semantics, for each accepted tag.

Clients MAY see other status codes (`431 Request Header Fields Too Large`) depending on the registry implementation.

Expand Down Expand Up @@ -580,7 +580,7 @@ In this case, the path will look like the following: `/v2/<name>/tags/list?n=<in
The response to such a request MAY return fewer than `<int>` results, but only when the total number of tags attached to the repository is less than `<int>` or a `Link` header is provided.
Otherwise, the response MUST include `<int>` results.
A `Link` header MAY be included in the response when additional tags are available.
If included, the `Link` header MUST be set according to [RFC5988](https://www.rfc-editor.org/rfc/rfc5988.html) with the Relation Type `rel="next"`.
If included, the `Link` header MUST be set according to [RFC 5988](https://www.rfc-editor.org/rfc/rfc5988) with the Relation Type `rel="next"`.
When `n` is zero, this endpoint MUST return an empty list, and MUST NOT include a `Link` header.
Without the `last` query parameter (described next), the list returned will start at the beginning of the list and include `<int>` results.
As above, the tags MUST be in lexical or "ASCIIbetical" order.
Expand Down Expand Up @@ -662,7 +662,7 @@ If a query results in no matching referrers, an empty manifest list MUST be retu

A `Link` header MUST be included in the response when the descriptor list cannot be returned in a single manifest.
Each response is an image index with different descriptors in the `manifests` field.
The `Link` header MUST be set according to [RFC5988](https://www.rfc-editor.org/rfc/rfc5988.html) with the Relation Type `rel="next"`.
The `Link` header MUST be set according to [RFC 5988](https://www.rfc-editor.org/rfc/rfc5988) with the Relation Type `rel="next"`.

The registry SHOULD support filtering on `artifactType`.
To fetch the list of referrers with a filter, perform a `GET` request to a path in the following format: `/v2/<name>/referrers/<digest>?artifactType=<artifactType>` <sup>[end-12b](#endpoints)</sup>.
Expand Down Expand Up @@ -812,7 +812,11 @@ When registries add support for the referrers API, this API needs to account for

## API

The API operates over HTTP. Below is a summary of the endpoints used by the API.
The API operates over HTTP.
Where this specification does not define specific behavior, implementations SHOULD follow the HTTP semantics defined in [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110).
Registries MAY respond to any request with a redirect per [RFC 9110 (section 15.4)](https://www.rfc-editor.org/rfc/rfc9110#section-15.4); clients MUST follow such redirects, and MUST NOT forward `Authorization` headers across host boundaries unless explicitly configured to do so.
Copy link
Copy Markdown
Member

@mikebrow mikebrow Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Registries MAY respond to any request with a redirect per [RFC 9110 (section 15.4)](https://www.rfc-editor.org/rfc/rfc9110#section-15.4); clients MUST follow such redirects, and MUST NOT forward `Authorization` headers across host boundaries unless explicitly configured to do so.
Registries MAY respond to any request with a redirect per [RFC 9110 (section 15.4)](https://www.rfc-editor.org/rfc/rfc9110#section-15.4); clients following such redirects MUST NOT forward `Authorization` headers across host boundaries unless explicitly configured to do so.

Don't think we should force clients to accept redirects, that feels like an optional consideration.

Copy link
Copy Markdown
Member Author

@tianon tianon Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not "forcing", it's documenting reality.

Do you have a counter example of a client that doesn't follow redirects today? Any such client won't work against almost every single major registry, which is really compelling evidence for "this should be normative in the spec"

Copy link
Copy Markdown
Member

@mikebrow mikebrow Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

keyword .. "should be normative" not MUST follow.. should be noted that in some circles redirects are not normative.

Not aware of any clients that disallow redirects outside some restrictions on the number of redirects.

Copy link
Copy Markdown
Member

@mikebrow mikebrow Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/containerd/containerd/blob/main/core/remotes/docker/resolver.go#L649-L651

Copy link
Copy Markdown
Member Author

@tianon tianon Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Limiting the number of redirects followed is totally reasonable and actually called out in the RFC itself:

A client SHOULD detect and intervene in cyclical redirections (i.e., "infinite" redirection loops).

Note: An earlier version of this specification recommended a maximum of five redirections ([RFC2068], Section 10.3). Content developers need to be aware that some clients might implement such a fixed limitation.

I'd be willing to soften to a SHOULD from a MUST, but removing the strong language is (IMO) not being honest about how this actually works in practice -- for example, any client that doesn't follow redirects at all will literally not work with any of the largest public registries. That's stronger ecosystem evidence than would be covered by just a recommendation.

Copy link
Copy Markdown
Member

@mikebrow mikebrow Apr 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Limiting the number of redirects followed is totally reasonable and actually called out in the RFC itself:

A client SHOULD detect and intervene in cyclical redirections (i.e., "infinite" redirection loops).

Note: An earlier version of this specification recommended a maximum of five redirections ([RFC2068], Section 10.3). Content developers need to be aware that some clients might implement such a fixed limitation.

I'd be willing to soften to a SHOULD from a MUST, but removing the strong language is (IMO) not being honest about how this actually works in practice -- for example, any client that doesn't follow redirects at all will literally not work with any of the largest public registries. That's stronger ecosystem evidence than would be covered by just a recommendation.

soften to SHOULD language SGTM

I think it would also be fair to mention the need for reasoned following of redirects to enable working with the preponderance of public registries. Another reasonable response might be to check redirect allowance config for certain regions / providers, or just to include an info/debug log of the redirects so as not to hide them from the user.. etc..

The status codes documented in this specification are those returned after any redirects have been followed.
Below is a summary of the endpoints used by the API.

### Determining Support

Expand Down Expand Up @@ -886,9 +890,11 @@ The `code` field MUST be one of the following:
| code-13 | `UNSUPPORTED` | the operation is unsupported |
| code-14 | `TOOMANYREQUESTS` | too many requests |

A `429 Too Many Requests` response ([RFC 6585 (section 4)](https://www.rfc-editor.org/rfc/rfc6585#section-4)) SHOULD include a `Retry-After` header per [RFC 9110 (section 10.2.3)](https://www.rfc-editor.org/rfc/rfc9110#section-10.2.3).

### Warnings

Registry implementations MAY include informational warnings in `Warning` headers, as described in [RFC 7234](https://www.rfc-editor.org/rfc/rfc7234#section-5.5).
Registry implementations MAY include informational warnings in `Warning` headers, as described in [RFC 7234 (section 5.5)](https://www.rfc-editor.org/rfc/rfc7234#section-5.5).

If included, `Warning` headers MUST specify a `warn-code` of `299` and a `warn-agent` of `-`, and MUST NOT specify a `warn-date` value.

Expand Down
Loading