Skip to content

Commit 2cf40ab

Browse files
dmcgowandmcgowan
committed
Modify blob upload API
- Ensures new uploads and resumed upload statuses always return an offset of 0. This allows future clients which support resumable upload to not attempt resumable upload on this version which does not support it. - Add PATCH support for streaming data on upload. - Add messaging to specification that PATCH with content range is currently not supported. - Update PUT blob to only support full data or no data, no more last chunk messaging as it was not supported. closes distribution#470 Signed-off-by: Derek McGowan <[email protected]> (github: dmcgowan)
1 parent f210b09 commit 2cf40ab

File tree

6 files changed

+405
-84
lines changed

6 files changed

+405
-84
lines changed

‎docs/spec/api.md

+160-26
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,9 @@ specification to correspond with the versions enumerated here.
123123
<li>Deleting a manifest by tag has been deprecated.</li>
124124
<li>Specified `Docker-Content-Digest` header for appropriate entities.</li>
125125
<li>Added error code for unsupported operations.</li>
126+
<li>Added capability of doing streaming upload to PATCH blob upload.</li>
127+
<li>Updated PUT blob upload to no longer take final chunk, now requires entire data or no data.</li>
128+
<li>Removed 416 return code from PUT blob upload.</li>
126129
</ul>
127130
</dd>
128131

@@ -2175,6 +2178,158 @@ The error codes that may be included in the response body are enumerated below:
21752178
Upload a chunk of data for the specified upload.
21762179

21772180

2181+
##### Stream upload
2182+
2183+
```
2184+
PATCH /v2/<name>/blobs/uploads/<uuid>
2185+
Host: <registry host>
2186+
Authorization: <scheme> <token>
2187+
Content-Type: application/octet-stream
2188+
2189+
<binary data>
2190+
```
2191+
2192+
Upload a stream of data to upload without completing the upload.
2193+
2194+
2195+
The following parameters should be specified on the request:
2196+
2197+
|Name|Kind|Description|
2198+
|----|----|-----------|
2199+
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
2200+
|`Authorization`|header|An RFC7235 compliant authorization header.|
2201+
|`name`|path|Name of the target repository.|
2202+
|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
2203+
2204+
2205+
2206+
2207+
###### On Success: Data Accepted
2208+
2209+
```
2210+
204 No Content
2211+
Location: /v2/<name>/blobs/uploads/<uuid>
2212+
Range: 0-<offset>
2213+
Content-Length: 0
2214+
Docker-Upload-UUID: <uuid>
2215+
```
2216+
2217+
The stream of data has been accepted and the current progress is available in the range header. The updated upload location is available in the `Location` header.
2218+
2219+
The following headers will be returned with the response:
2220+
2221+
|Name|Description|
2222+
|----|-----------|
2223+
|`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.|
2224+
|`Range`|Range indicating the current progress of the upload.|
2225+
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
2226+
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
2227+
2228+
2229+
2230+
2231+
###### On Failure: Bad Request
2232+
2233+
```
2234+
400 Bad Request
2235+
Content-Type: application/json; charset=utf-8
2236+
2237+
{
2238+
"errors:" [
2239+
{
2240+
"code": <error code>,
2241+
"message": "<error message>",
2242+
"detail": ...
2243+
},
2244+
...
2245+
]
2246+
}
2247+
```
2248+
2249+
There was an error processing the upload and it must be restarted.
2250+
2251+
2252+
2253+
The error codes that may be included in the response body are enumerated below:
2254+
2255+
|Code|Message|Description|
2256+
-------|----|------|------------
2257+
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
2258+
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
2259+
| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
2260+
2261+
2262+
2263+
###### On Failure: Unauthorized
2264+
2265+
```
2266+
401 Unauthorized
2267+
WWW-Authenticate: <scheme> realm="<realm>", ..."
2268+
Content-Length: <length>
2269+
Content-Type: application/json; charset=utf-8
2270+
2271+
{
2272+
"errors:" [
2273+
{
2274+
"code": "UNAUTHORIZED",
2275+
"message": "access to the requested resource is not authorized",
2276+
"detail": ...
2277+
},
2278+
...
2279+
]
2280+
}
2281+
```
2282+
2283+
The client does not have access to push to the repository.
2284+
2285+
The following headers will be returned on the response:
2286+
2287+
|Name|Description|
2288+
|----|-----------|
2289+
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
2290+
|`Content-Length`|Length of the JSON error response body.|
2291+
2292+
2293+
2294+
The error codes that may be included in the response body are enumerated below:
2295+
2296+
|Code|Message|Description|
2297+
-------|----|------|------------
2298+
| `UNAUTHORIZED` | access to the requested resource is not authorized | The access controller denied access for the operation on a resource. Often this will be accompanied by a 401 Unauthorized response status. |
2299+
2300+
2301+
2302+
###### On Failure: Not Found
2303+
2304+
```
2305+
404 Not Found
2306+
Content-Type: application/json; charset=utf-8
2307+
2308+
{
2309+
"errors:" [
2310+
{
2311+
"code": <error code>,
2312+
"message": "<error message>",
2313+
"detail": ...
2314+
},
2315+
...
2316+
]
2317+
}
2318+
```
2319+
2320+
The upload is unknown to the registry. The upload must be restarted.
2321+
2322+
2323+
2324+
The error codes that may be included in the response body are enumerated below:
2325+
2326+
|Code|Message|Description|
2327+
-------|----|------|------------
2328+
| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. |
2329+
2330+
2331+
2332+
##### Chunked upload
21782333

21792334
```
21802335
PATCH /v2/<name>/blobs/uploads/<uuid>
@@ -2187,7 +2342,7 @@ Content-Type: application/octet-stream
21872342
<binary chunk>
21882343
```
21892344

2190-
Upload a chunk of data to specified upload without completing the upload.
2345+
Upload a chunk of data to specified upload without completing the upload. The data will be uploaded to the specified Content Range.
21912346

21922347

21932348
The following parameters should be specified on the request:
@@ -2350,14 +2505,13 @@ Complete the upload specified by `uuid`, optionally appending the body as the fi
23502505
PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>
23512506
Host: <registry host>
23522507
Authorization: <scheme> <token>
2353-
Content-Range: <start of range>-<end of range, inclusive>
2354-
Content-Length: <length of chunk>
2508+
Content-Length: <length of data>
23552509
Content-Type: application/octet-stream
23562510
2357-
<binary chunk>
2511+
<binary data>
23582512
```
23592513

2360-
Complete the upload, providing the _final_ chunk of data, if necessary. This method may take a body with all the data. If the `Content-Range` header is specified, it may include the final chunk. A request without a body will just complete the upload with previously uploaded content.
2514+
Complete the upload, providing all the data in the body, if necessary. A request without a body will just complete the upload with previously uploaded content.
23612515

23622516

23632517
The following parameters should be specified on the request:
@@ -2366,8 +2520,7 @@ The following parameters should be specified on the request:
23662520
|----|----|-----------|
23672521
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
23682522
|`Authorization`|header|An RFC7235 compliant authorization header.|
2369-
|`Content-Range`|header|Range of bytes identifying the 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. May be omitted if no data is provided.|
2370-
|`Content-Length`|header|Length of the chunk being uploaded, corresponding to the length of the request body. May be zero if no data is provided.|
2523+
|`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.|
23712524
|`name`|path|Name of the target repository.|
23722525
|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
23732526
|`digest`|query|Digest of uploaded blob.|
@@ -2500,25 +2653,6 @@ The error codes that may be included in the response body are enumerated below:
25002653

25012654

25022655

2503-
###### On Failure: Requested Range Not Satisfiable
2504-
2505-
```
2506-
416 Requested Range Not Satisfiable
2507-
Location: /v2/<name>/blobs/uploads/<uuid>
2508-
Range: 0-<offset>
2509-
```
2510-
2511-
The `Content-Range` specification cannot be accepted, either because it does not overlap with the current progress or it is invalid. The contents of the `Range` header may be used to resolve the condition.
2512-
2513-
The following headers will be returned on the response:
2514-
2515-
|Name|Description|
2516-
|----|-----------|
2517-
|`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.|
2518-
|`Range`|Range indicating the current progress of the upload.|
2519-
2520-
2521-
25222656

25232657
#### DELETE Blob Upload
25242658

‎docs/spec/api.md.tmpl

+3
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,9 @@ specification to correspond with the versions enumerated here.
123123
<li>Deleting a manifest by tag has been deprecated.</li>
124124
<li>Specified `Docker-Content-Digest` header for appropriate entities.</li>
125125
<li>Added error code for unsupported operations.</li>
126+
<li>Added capability of doing streaming upload to PATCH blob upload.</li>
127+
<li>Updated PUT blob upload to no longer take final chunk, now requires entire data or no data.</li>
128+
<li>Removed 416 return code from PUT blob upload.</li>
126129
</ul>
127130
</dd>
128131

‎docs/spec/implementations.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Distribution API Implementations
2+
3+
This is a list of known implementations of the Distribution API spec.
4+
5+
## [Docker Distribution Registry](https://github.com/docker/distribution)
6+
7+
Docker distribution is the reference implementation of the distribution API
8+
specification. It aims to fully implement the entire specification.
9+
10+
### Releases
11+
#### 2.0.1 (_in development_)
12+
Implements API 2.0.1
13+
14+
_Known Issues_
15+
- No resumable push support
16+
- Content ranges ignored
17+
- Blob upload status will always return a starting range of 0
18+
19+
#### 2.0.0
20+
Implements API 2.0.0
21+
22+
_Known Issues_
23+
- No resumable push support
24+
- No PATCH implementation for blob upload
25+
- Content ranges ignored
26+

0 commit comments

Comments
 (0)