From 82ac37ec2aee9f9ea94d3e32785922e9cbcf27d9 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Thu, 23 Apr 2026 11:06:13 -0700 Subject: [PATCH] Permit HTTP redirects globally and add RFC references - allow registries to redirect any request per RFC 9110 (section 15.4); status codes in this spec are those returned after redirects have been followed; clients MUST NOT forward `Authorization` headers across host boundaries - add 429 / Retry-After guidance per RFC 6585 (section 4) and RFC 9110 (section 10.2.3) - note that RFC 9110 governs HTTP behaviors not otherwise specified - normalize all RFC citations to consistent rfc-editor.org URLs with section numbers in link text Signed-off-by: Tianon Gravi --- spec.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/spec.md b/spec.md index 091bb2b9..e7eb79cd 100644 --- a/spec.md +++ b/spec.md @@ -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 @@ -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`. @@ -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 @@ -256,7 +256,7 @@ The `` 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 `` has been obtained, perform the upload proper by making a `PUT` request to the following URL path, and with the following headers and body: @@ -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//manifests/` [end-7](#endpoints) 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. @@ -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. @@ -580,7 +580,7 @@ In this case, the path will look like the following: `/v2//tags/list?n=` results, but only when the total number of tags attached to the repository is less than `` or a `Link` header is provided. Otherwise, the response MUST include `` 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 `` results. As above, the tags MUST be in lexical or "ASCIIbetical" order. @@ -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//referrers/?artifactType=` [end-12b](#endpoints). @@ -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. +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 @@ -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.