Skip to content

Commit

Permalink
Incorporate SE-0292 feedback into RegistryDraft (Third Review) (#3541)
Browse files Browse the repository at this point in the history 
* A client MUST verify the integrity of a downloaded source archive
* Replace instances of SHALL with MUST
* Remove Etag headers from example responses
* Add operationId properties to endpoints in OpenAPI specification
* Add redirect response to OpenAPI specification
* Add Content-Length headers to examples and OpenAPI specification
* Add Digest and Content-Length headers to responses in OpenAPI specification
* Rename RegistryDraft.md to Registry.md
  • Loading branch information
@mattt
mattt committed Jun 25, 2021
1 parent edb86a3 commit e3ea6ed
Showing 1 changed file with 47 additions and 17 deletions.
64 changes: 47 additions & 17 deletions Documentation/RegistryDraft.md → Documentation/Registry.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ Valid `Accept` header field values are described by the following rules:
accept = "application/vnd.swift.registry" [".v" version] ["+" mediatype]
```

A server SHALL set the `Content-Type` and `Content-Version` header fields
A server MUST set the `Content-Type` and `Content-Version` header fields
with the corresponding content type and API version number of the response.

```http
Expand Down Expand Up @@ -316,6 +316,7 @@ containing the releases for the requested package.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Version: 1
Content-Length: 508
Link: <https://github.com/mona/LinkedList>; rel="canonical",
<ssh://git@github.com:mona/LinkedList.git>; rel="alternate",
<https://packages.example.com/mona/LinkedList/1.1.1>; rel="latest-version",
Expand All @@ -341,7 +342,7 @@ Link: <https://github.com/mona/LinkedList>; rel="canonical",
}
```

The response body SHALL contain a JSON object
The response body MUST contain a JSON object
nested at a top-level `releases` key,
whose keys are version numbers for releases and
whose values are objects containing the following fields:
Expand Down Expand Up @@ -426,8 +427,9 @@ Otherwise, a server SHOULD respond with a status code of `404` (Not Found).

```http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Version: 1
Content-Type: application/json
Content-Length: 620
Link: <https://packages.example.com/mona/LinkedList/1.1.1>; rel="latest-version",
<https://packages.example.com/mona/LinkedList/1.0.0>; rel="predecessor-version"
```
Expand Down Expand Up @@ -504,7 +506,6 @@ Content-Type: text/x-swift
Content-Disposition: attachment; filename="Package.swift"
Content-Length: 361
Content-Version: 1
ETag: 87e749848e0fc4cfc509e4090ca37773
Link: <http://packages.example.com/mona/LinkedList/Package.swift?swift-version=4>; rel="alternate",
<http://packages.example.com/mona/LinkedList/Package.swift?swift-version=4.2>; rel="alternate"
Expand Down Expand Up @@ -566,7 +567,6 @@ Content-Type: text/x-swift
Content-Disposition: attachment; filename="Package@swift-4.2.swift"
Content-Length: 361
Content-Version: 1
ETag: 24f6cd72352c4201df22a5be356d4d22
// swift-tools-version:4.2
import PackageDescription
Expand Down Expand Up @@ -625,16 +625,15 @@ Content-Disposition: attachment; filename="LinkedList-1.1.1.zip"
Content-Length: 2048
Content-Version: 1
Digest: sha-256=a2ac54cf25fbc1ad0028f03f0aa4b96833b83bb05a14e510892bb27dea4dc812
ETag: e61befdd5056d4b8bafa71c5bbb41d71
Link: <https://mirror-japanwest.example.com/mona-LinkedList-1.1.1.zip>; rel=duplicate; geo=jp; pri=10; type="application/zip"
```

A server SHALL respond with a `Content-Length` header
A server MUST respond with a `Content-Length` header
set to the size of the archive in bytes.
A client SHOULD terminate any requests whose response exceeds
the expected content length.

A server SHALL respond with a `Digest` header
A server MUST respond with a `Digest` header
containing a SHA-256 checksum for the source archive.

A server SHOULD respond with a `Content-Disposition` header
Expand All @@ -648,7 +647,7 @@ and caching as described by [RFC 7234].

#### 4.4.1. Integrity verification

A client SHOULD verify the integrity of a downloaded source archive
A client MUST verify the integrity of a downloaded source archive
using the checksum provided in the `Digest` header of a response
(for example, using the command
`echo "$CHECKSUM LinkedList-1.1.1.zip" | shasum -a 256 -c`).
Expand All @@ -663,15 +662,22 @@ A client MAY use this information
to determine its preferred strategy for downloading.

A server that indexes but doesn't host packages
SHOULD respond with a status code of `303` (See Other)
MAY respond with a status code of `303` (See Other)
and redirect to a hosted package archive if one is available.

```http
HTTP/1.1 303 See Other
Content-Version: 1
Content-Length: 2048
Digest: sha-256=a2ac54cf25fbc1ad0028f03f0aa4b96833b83bb05a14e510892bb27dea4dc812
Location: https://packages.example.com/mona/LinkedList/1.1.1.zip
```

The client SHOULD consider the `Digest` and `Content-Length` headers
sent in the response to be authoritative for the redirected resource.
The client MUST NOT follow redirects that downgrade to an insecure connection.
The client SHOULD limit the number of redirects to prevent a redirect loop.

<a name="endpoint-5"></a>

### 4.5 Lookup package identifiers registered for a URL
Expand Down Expand Up @@ -708,7 +714,7 @@ Content-Version: 1
}
```

The response body SHALL contain an array of package identifier strings
The response body MUST contain an array of package identifier strings
nested at a top-level `identifiers` key.

It is RECOMMENDED for clients and servers to support
Expand Down Expand Up @@ -770,6 +776,7 @@ paths:
tags:
- Package
summary: List package releases
operationId: listPackageReleases
parameters:
- name: Content-Type
in: header
Expand All @@ -783,6 +790,9 @@ paths:
headers:
Content-Version:
$ref: "#/components/headers/contentVersion"
Content-Length:
schema:
type: integer
content:
application/json:
schema:
Expand All @@ -801,6 +811,7 @@ paths:
tags:
- Release
summary: Fetch release metadata
operationId: fetchReleaseMetadata
parameters:
- name: Content-Type
in: header
Expand All @@ -814,6 +825,9 @@ paths:
headers:
Content-Version:
$ref: "#/components/headers/contentVersion"
Content-Length:
schema:
type: integer
content:
application/json:
schema:
Expand All @@ -832,6 +846,7 @@ paths:
tags:
- Release
summary: Fetch manifest for a package release
operationId: fetchManifestForPackageRelease
parameters:
- name: Content-Type
in: header
Expand All @@ -855,9 +870,6 @@ paths:
type: integer
Content-Version:
$ref: "#/components/headers/contentVersion"
Etag:
schema:
type: string
Link:
schema:
type: string
Expand All @@ -879,6 +891,7 @@ paths:
tags:
- Release
summary: Download source archive
operationId: downloadSourceArchive
parameters:
- name: Content-Type
in: header
Expand Down Expand Up @@ -908,9 +921,6 @@ paths:
required: true
schema:
type: string
Etag:
schema:
type: string
Link:
schema:
type: string
Expand All @@ -919,6 +929,8 @@ paths:
schema:
type: string
format: binary
3XX:
$ref: "#/components/responses/redirect"
4XX:
$ref: "#/components/responses/problemDetails"
/identifiers:
Expand All @@ -928,6 +940,7 @@ paths:
tags:
- Package
summary: Lookup package identifiers registered for a URL
operationId: lookupPackageIdentifiersByURL
parameters:
- name: Content-Type
in: header
Expand Down Expand Up @@ -1012,10 +1025,27 @@ components:
Content-Language:
schema:
type: string
Content-Length:
schema:
type: integer
content:
application/problem+json:
schema:
$ref: "#/components/schemas/problem"
redirect:
description: A server redirect.
headers:
Content-Version:
$ref: "#/components/headers/contentVersion"
Location:
schema:
type: string
Digest:
schema:
type: string
Content-Length:
schema:
type: integer
parameters:
scope:
name: scope
Expand Down

0 comments on commit e3ea6ed

Please sign in to comment.