From 35c06bdf7e266ca5a85f2c5f9dd23599a9ac3aed Mon Sep 17 00:00:00 2001 From: Vincent Batts Date: Fri, 20 Dec 2019 11:02:11 -0500 Subject: [PATCH] spec: session_id is clearer than UUID the behavior previously described as `UUID` is really a session ID. For implementations with existing behavior this is a nop, but going forward the header `Blob-Upload-Session-ID` is more clear than `Docker-Upload-UUID`. Fixes #13 Signed-off-by: Vincent Batts --- spec.md | 102 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/spec.md b/spec.md index ccd2ad4f..d794885c 100644 --- a/spec.md +++ b/spec.md @@ -425,7 +425,7 @@ If the POST request is successful, a `202 Accepted` response will be returned wi ```HTTP 202 Accepted -Location: /v2//blobs/uploads/ +Location: /v2//blobs/uploads/ Range: bytes=0- Content-Length: 0 ``` @@ -433,11 +433,11 @@ Content-Length: 0 The rest of the upload process can be carried out with the returned url, called the "Upload URL" from the `Location` header. All responses to the upload url, whether sending data or getting status, will be in this format. -Though the URI format (`/v2//blobs/uploads/`) for the `Location` header is specified, clients SHOULD treat it as an opaque url and SHOULD never try to assemble it. -While the `uuid` parameter MAY be an actual UUID, this proposal imposes no constraints on the format and clients SHOULD never impose any. +Though the URI format (`/v2//blobs/uploads/`) for the `Location` header is specified, clients SHOULD treat it as an opaque url and SHOULD never try to assemble it. +While the `session_id` parameter MAY be an actual UUID, this proposal imposes no constraints on the format and clients SHOULD never impose any. -Header `Blob-Upload-UUID` OPTIONAL: If clients need to correlate local upload state with remote upload state, largely for resumable uploads. -Header `Docker-Upload-UUID` OPTIONAL: legacy compatibility +Header `Blob-Upload-Session-ID` OPTIONAL: If clients need to correlate local upload state with remote upload state, largely for resumable uploads. +Header `Docker-Upload-UUID` OPTIONAL: legacy compatibility. Not contstrained to being an official UUID. ##### Upload Progress @@ -452,7 +452,7 @@ Range: bytes=0-0 To get the status of an upload, issue a GET request to the upload URL: ```HTTP -GET /v2//blobs/uploads/ +GET /v2//blobs/uploads/ Host: ``` @@ -460,7 +460,7 @@ The response will be similar to the above, except will return 204 status: ```HTTP 204 No Content -Location: /v2//blobs/uploads/ +Location: /v2//blobs/uploads/ Range: bytes=0- ``` @@ -472,7 +472,7 @@ A monolithic upload is simply a chunked upload with a single chunk and MAY be fa To carry out a "monolithic" upload, one can simply put the entire content blob to the provided URL: ```HTTP -PUT /v2//blobs/uploads/?digest= +PUT /v2//blobs/uploads/?digest= Content-Length: Content-Type: application/octet-stream @@ -487,7 +487,7 @@ Please see the [_Completed Upload_](#completed-upload) section for details on th To carry out an upload of a chunk, the client can specify a range header and only include that part of the layer file: ```HTTP -PATCH /v2//blobs/uploads/ +PATCH /v2//blobs/uploads/ Content-Length: Content-Range: - Content-Type: application/octet-stream @@ -501,10 +501,10 @@ If the server cannot accept the chunk, a `416 Requested Range Not Satisfiable` r ```HTTP 416 Requested Range Not Satisfiable -Location: /v2//blobs/uploads/ +Location: /v2//blobs/uploads/ Range: 0- Content-Length: 0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` If this response is received, the client SHOULD resume from the "last valid range" and upload the subsequent chunk. @@ -517,10 +517,10 @@ When a chunk is accepted as part of the upload, a `202 Accepted` response will b ```HTTP 202 Accepted -Location: /v2//blobs/uploads/ +Location: /v2//blobs/uploads/ Range: bytes=0- Content-Length: 0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` ##### Completed Upload @@ -530,7 +530,7 @@ If it is not provided, the upload will not be considered complete. The format for the final chunk will be as follows: ```HTTP -PUT /v2//blobs/uploads/?digest= +PUT /v2//blobs/uploads/?digest= Content-Length: Content-Range: - Content-Type: application/octet-stream @@ -572,10 +572,10 @@ An upload can be cancelled by issuing a DELETE request to the upload endpoint. The format will be as follows: ```HTTP -DELETE /v2//blobs/uploads/ +DELETE /v2//blobs/uploads/ ``` -After this request is issued, the upload uuid will no longer be valid and the registry server will dump all intermediate data. +After this request is issued, the upload `session_id` will no longer be valid and the registry server will dump all intermediate data. While uploads will time out if not completed, clients SHOULD issue this request if they encounter a fatal error but still have the ability to issue an http request. ##### Cross Repository Blob Mount @@ -605,10 +605,10 @@ If a mount fails due to invalid repository or digest arguments, the registry wil ```HTTP 202 Accepted -Location: /v2//blobs/uploads/ +Location: /v2//blobs/uploads/ Range: bytes=0- Content-Length: 0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` This behavior is consistent with older versions of the registry, which do not recognize the repository mount query parameters. @@ -624,7 +624,7 @@ If there is a problem with the upload, a 4xx error will be returned indicating t After receiving a 4xx response (except 416, as called out above), the upload will be considered failed and the client SHOULD take appropriate action. Note that the upload url will not be available forever. -If the upload uuid is unknown to the registry, a `404 Not Found` response will be returned and the client MUST restart the upload process. +If the upload `session_id` is unknown to the registry, a `404 Not Found` response will be returned and the client MUST restart the upload process. #### Deleting a Layer @@ -852,10 +852,10 @@ A list of methods and URIs are covered in the table below: | GET | `/v2//blobs/` | Blob | Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data. | | DELETE | `/v2//blobs/` | Blob | Delete the blob identified by `name` and `digest` | | POST | `/v2//blobs/uploads/` | Initiate Blob Upload | Initiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if the `digest` parameter is present, the request body will be used to complete the upload in a single request. | -| GET | `/v2//blobs/uploads/` | Blob Upload | Retrieve status of upload identified by `uuid`. The primary purpose of this endpoint is to resolve the current status of a resumable upload. | -| PATCH | `/v2//blobs/uploads/` | Blob Upload | Upload a chunk of data for the specified upload. | -| PUT | `/v2//blobs/uploads/` | Blob Upload | Complete the upload specified by `uuid`, optionally appending the body as the final chunk. | -| DELETE | `/v2//blobs/uploads/` | Blob Upload | Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. | +| GET | `/v2//blobs/uploads/` | Blob Upload | Retrieve status of upload identified by `session_id`. The primary purpose of this endpoint is to resolve the current status of a resumable upload. | +| PATCH | `/v2//blobs/uploads/` | Blob Upload | Upload a chunk of data for the specified upload. | +| PUT | `/v2//blobs/uploads/` | Blob Upload | Complete the upload specified by `session_id`, optionally appending the body as the final chunk. | +| DELETE | `/v2//blobs/uploads/` | Blob Upload | Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. | The detail for each endpoint is covered in the following sections. ### Errors @@ -2833,7 +2833,7 @@ The following parameters SHOULD be specified on the request: 201 Created Location: Content-Length: 0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` The blob has been created in the registry and is available at the provided location. @@ -2844,7 +2844,7 @@ The following headers will be returned with the response: |----------------------|----------------------------------------------------------------------| | `Location` | | | `Content-Length` | The `Content-Length` header MUST be zero and the body MUST be empty. | -| `Blob-Upload-UUID` | Identifies the upload uuid for the current request. | +| `Blob-Upload-Session-ID` | Identifies the upload session_id for the current request. | ###### On Failure: Invalid Name or Digest @@ -3032,9 +3032,9 @@ The following parameters SHOULD be specified on the request: ```HTTP 202 Accepted Content-Length: 0 -Location: /v2//blobs/uploads/ +Location: /v2//blobs/uploads/ Range: 0-0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` The upload has been created. @@ -3048,7 +3048,7 @@ The following headers will be returned with the response: | `Content-Length` | The `Content-Length` header MUST be zero and the body MUST be empty. | | `Location` | The location of the created upload.Clients SHOULD use the contents verbatim to complete the upload, adding parameters where required. | | `Range` | Range header indicating the progress of the upload.When starting an upload, it will return an empty range, since no content has been received. | -| `Blob-Upload-UUID` | Identifies the upload uuid for the current request. | +| `Blob-Upload-Session-ID` | Identifies the upload session_id for the current request. | ###### On Failure: Invalid Name or Digest @@ -3225,7 +3225,7 @@ The following parameters SHOULD be specified on the request: 201 Created Location: Content-Length: 0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` The blob has been mounted in the repository and is available at the provided location. @@ -3236,7 +3236,7 @@ The following headers will be returned with the response: |----------------------|----------------------------------------------------------------------| | `Location` | | | `Content-Length` | The `Content-Length` header MUST be zero and the body MUST be empty. | -| `Blob-Upload-UUID` | Identifies the upload uuid for the current request. | +| `Blob-Upload-Session-ID` | Identifies the upload session_id for the current request. | ###### On Failure: Invalid Name or Digest @@ -3407,11 +3407,11 @@ The `Location` header and its parameters SHOULD be preserved by clients, using t #### GET Blob Upload -Retrieve status of upload identified by `uuid`. +Retrieve status of upload identified by `session_id`. The primary purpose of this endpoint is to resolve the current status of a resumable upload. ```HTTP -GET /v2//blobs/uploads/ +GET /v2//blobs/uploads/ Host: Authorization: ``` @@ -3425,7 +3425,7 @@ The following parameters SHOULD be specified on the request: | `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. | | `Authorization` | header | An RFC7235 compliant authorization header. | | `name` | path | Name of the target repository. | -| `uuid` | path | A uuid identifying the upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | +| `session_id` | path | A unique string identifying session of the particular upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | ###### On Success: Upload Progress @@ -3433,7 +3433,7 @@ The following parameters SHOULD be specified on the request: 204 No Content Range: 0- Content-Length: 0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` The upload is known and in progress. @@ -3445,7 +3445,7 @@ The following headers will be returned with the response: |----------------------|----------------------------------------------------------------------| | `Range` | Range indicating the current progress of the upload. | | `Content-Length` | The `Content-Length` header MUST be zero and the body MUST be empty. | -| `Blob-Upload-UUID` | Identifies the upload uuid for the current request. | +| `Blob-Upload-Session-ID` | Identifies the upload session ID for the current request. | ###### On Failure: Bad Request @@ -3643,7 +3643,7 @@ Upload a chunk of data for the specified upload. ##### Stream upload ```HTTP -PATCH /v2//blobs/uploads/ +PATCH /v2//blobs/uploads/ Host: Authorization: Content-Type: application/octet-stream @@ -3660,16 +3660,16 @@ The following parameters SHOULD be specified on the request: | `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. | | `Authorization` | header | An RFC7235 compliant authorization header. | | `name` | path | Name of the target repository. | -| `uuid` | path | A uuid identifying the upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | +| `session_id` | path | A unique string identifying the upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | ###### On Success: Data Accepted ```HTTP 202 Accepted -Location: /v2//blobs/uploads/ +Location: /v2//blobs/uploads/ Range: 0- Content-Length: 0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` The stream of data has been accepted and the current progress is available in the range header. @@ -3682,7 +3682,7 @@ The following headers will be returned with the response: | `Location` | The location of the upload.Clients SHOULD assume this changes after each request.Clients SHOULD use the contents verbatim to complete the upload, adding parameters where required. | | `Range` | Range indicating the current progress of the upload. | | `Content-Length` | The `Content-Length` header MUST be zero and the body MUST be empty. | -| `Blob-Upload-UUID` | Identifies the upload uuid for the current request. | +| `Blob-Upload-Session-ID` | Identifies the upload session ID for the current request. | ###### On Failure: Bad Request @@ -3876,7 +3876,7 @@ The error codes that MAY be included in the response body are enumerated below: ##### Chunked upload ```HTTP -PATCH /v2//blobs/uploads/ +PATCH /v2//blobs/uploads/ Host: Authorization: Content-Range: - @@ -3898,16 +3898,16 @@ The following parameters SHOULD be specified on the request: | `Content-Range` | header | Range of bytes identifying the desired block of content represented by the body.Start MUST the end offset retrieved via status check plus one.Note that this is a non-standard use of the `Content-Range` header. | | `Content-Length` | header | Length of the chunk being uploaded, corresponding the length of the request body. | | `name` | path | Name of the target repository. | -| `uuid` | path | A uuid identifying the upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | +| `session_id` | path | A unique string identifying session of the particular upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | ###### On Success: Chunk Accepted ```HTTP 202 Accepted -Location: /v2//blobs/uploads/ +Location: /v2//blobs/uploads/ Range: 0- Content-Length: 0 -Blob-Upload-UUID: +Blob-Upload-Session-ID: ``` The chunk of data has been accepted and the current progress is available in the range header. @@ -3920,7 +3920,7 @@ The following headers will be returned with the response: | `Location` | The location of the upload.Clients SHOULD assume this changes after each request.Clients SHOULD use the contents verbatim to complete the upload, adding parameters where required. | | `Range` | Range indicating the current progress of the upload. | | `Content-Length` | The `Content-Length` header MUST be zero and the body MUST be empty. | -| `Blob-Upload-UUID` | Identifies the upload uuid for the current request. | +| `Blob-Upload-Session-ID` | Identifies the upload session ID for the current request. | ###### On Failure: Bad Request @@ -4121,10 +4121,10 @@ The error codes that MAY be included in the response body are enumerated below: #### PUT Blob Upload -Complete the upload specified by `uuid`, optionally appending the body as the final chunk. +Complete the upload specified by `session_id`, optionally appending the body as the final chunk. ```HTTP -PUT /v2//blobs/uploads/?digest= +PUT /v2//blobs/uploads/?digest= Host: Authorization: Content-Length: @@ -4144,7 +4144,7 @@ The following parameters SHOULD be specified on the request: | `Authorization` | header | An RFC7235 compliant authorization header. | | `Content-Length` | header | Length of the data being uploaded, corresponding to the length of the request body.May be zero if no data is provided. | | `name` | path | Name of the target repository. | -| `uuid` | path | A uuid identifying the upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | +| `session_id` | path | A unique string identifying session of the particular upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | | `digest` | query | Digest of uploaded blob. | ###### On Success: Upload Complete @@ -4365,13 +4365,13 @@ Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. ```HTTP -DELETE /v2//blobs/uploads/ +DELETE /v2//blobs/uploads/ Host: Authorization: Content-Length: 0 ``` -Cancel the upload specified by `uuid`. +Cancel the upload specified by `session_id`. The following parameters SHOULD be specified on the request: @@ -4381,7 +4381,7 @@ The following parameters SHOULD be specified on the request: | `Authorization` | header | An RFC7235 compliant authorization header. | | `Content-Length` | header | The `Content-Length` header MUST be zero and the body MUST be empty. | | `name` | path | Name of the target repository. | -| `uuid` | path | A uuid identifying the upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | +| `session_id` | path | A unique string identifying session of the particular upload.This field can accept characters that match `[a-zA-Z0-9-_.=]+`. | ###### On Success: Upload Deleted