swiftlang · tomerd · Sep 15, 2021 · Jul 20, 2021 · Jul 22, 2021 · Jul 22, 2021
@@ -1,7 +1,4 @@
-# [DRAFT] Swift Package Registry Service Specification
-
-> **Important**
-> This is a draft pending the acceptance of [SE-0292](https://github.com/apple/swift-evolution/blob/main/proposals/0292-package-registry-service.md).
+# Swift Package Registry Service Specification
 
 - [1. Notations](#1-notations)
 - [2. Definitions](#2-definitions)
@@ -20,7 +17,7 @@
     - [4.2.1. Package release metadata standards](#421-package-release-metadata-standards)
   - [4.3. Fetch manifest for a package release](#43-fetch-manifest-for-a-package-release)
     - [4.3.1. swift-version query parameter](#431-swift-version-query-parameter)
-  - [4.4. Fetch source archive](#44-fetch-source-archive)
+  - [4.4. Download source archive](#44-download-source-archive)
     - [4.4.1. Integrity verification](#441-integrity-verification)
     - [4.4.2. Download locations](#442-download-locations)
   - [4.5 Lookup package identifiers registered for a URL](#45-lookup-package-identifiers-registered-for-a-url)
@@ -98,8 +95,7 @@ A server SHOULD communicate any errors to the client
 using "problem details" objects,
 as described by [RFC 7807].
 For example,
-a client sends a request to create a package release
-with an invalid `tag` parameter
+a client sends a request for a nonexistent release of a package
 and receives the following response:
 
 ```http
@@ -109,7 +105,7 @@ Content-Type: application/problem+json
 Content-Language: en
 
 {
-   "detail": "tag '2.0.0' not found"
+   "detail": "release not found"
 }
 ```
 
@@ -133,7 +129,7 @@ Retry-After: 60
 A client SHOULD follow the guidance of any
 `Retry-After` header values provided in responses
 to prevent overwhelming a server with retry requests.
-It is RECOMMENDED for clients to introduce randomness in their retry logic
+It is RECOMMENDED for clients to introduce random jitter in their retry logic
 to avoid a [thundering herd effect].
 
 ### 3.5. API versioning
@@ -186,7 +182,7 @@ Content-Version: 1
 ```
 
 If a client sends a request without an `Accept` header,
-a server MAY either return `400 Bad Request` or
+a server MAY either respond with a status code of `400 Bad Request` or
 process the request using an API version that it chooses,
 making sure to set the `Content-Type` and `Content-Version` headers accordingly.
 
@@ -256,19 +252,18 @@ Package scopes are case-insensitive
 #### 3.6.2 Package name
 
 A package's *name* uniquely identifies a package in a scope.
-The maximum length of a package name is 128 characters.
+A package name consists of alphanumeric characters, underscores, and hyphens.
+Hyphens and underscores may not occur at the beginning or end,
+nor consecutively within a name.
+The maximum length of a package name is 100 characters.
 A valid package name matches the following regular expression pattern:
 
 ```regexp
-\A\p{XID_Start}\p{XID_Continue}{0,127}\z
+\A[a-zA-Z0-9](?:[a-zA-Z0-9]|[-_](?=[a-zA-Z0-9])){0,99}\z
 ```
 
-> For more information,
-> see [Unicode Identifier and Pattern Syntax][UAX31].
-
-Package names are compared using
-[Normalization Form Compatible Composition (NFKC)][UAX15]
-with locale-independent case folding.
+Package names are case-insensitive
+(for example, `LinkedList` ≍ `LINKEDLIST`).
 
 ## 4. Endpoints
 
@@ -285,6 +280,14 @@ A server MUST respond to the following endpoints:
 A server SHOULD also respond to `HEAD` requests
 for each of the specified endpoints.
 
+A client MAY send an `OPTIONS` request with an asterisk (`*`)
+to determine the permitted communication options for the server.
+A server MAY respond with a `Link` header containing
+an entry for the `service-doc` relation type
+with a link to this document, and
+an entry for the `service-desc` relation type
+with a link to the OpenAPI specification.
+
 * * *
 
 <a name="endpoint-1"></a>
@@ -294,8 +297,8 @@ for each of the specified endpoints.
 A client MAY send a `GET` request
 for a URI matching the expression `/{scope}/{name}`
 to retrieve a list of the available releases for a particular package.
-A client SHOULD set the `Accept` header with
-the `application/vnd.swift.registry.v1+json` content type
+A client SHOULD set the `Accept` header with the value
+`application/vnd.swift.registry.v1+json`
 and MAY append the `.json` extension to the requested URI.
 
 ```http
@@ -354,7 +357,7 @@ whose values are objects containing the following fields:
 
 A server MAY specify a URL for a release using the `url` key.
 A client SHOULD locate a release using the value of the `url` key, if one is provided.
-Otherwise, the client SHOULD locate a release 
+Otherwise, the client SHOULD locate a release
 by expanding the URI Template `/{scope}/{name}/{version}` on the originating host.
 
 A server SHOULD communicate the unavailability of a package release
@@ -410,8 +413,8 @@ such as one with a `payment` relation for sponsoring a package maintainer.
 A client MAY send a `GET` request
 for a URI matching the expression `/{scope}/{name}/{version}`
 to retrieve metadata about a release.
-A client SHOULD set the `Accept` header with
-the `application/vnd.swift.registry.v1+json` content type,
+A client SHOULD set the `Accept` header with the value
+`application/vnd.swift.registry.v1+json`,
 and MAY append the `.json` extension to the requested URI.
 
 ```http
@@ -485,7 +488,7 @@ this response using the [Schema.org] [SoftwareSourceCode] vocabulary:
 A client MAY send a `GET` request for a URI matching the expression
 `/{scope}/{name}/{version}/Package.swift`
 to retrieve the package manifest for a release.
-A client SHOULD set the `Accept` header to
+A client SHOULD set the `Accept` header with the value
 `application/vnd.swift.registry.v1+swift`.
 
 ```http
@@ -506,8 +509,8 @@ Content-Type: text/x-swift
 Content-Disposition: attachment; filename="Package.swift"
 Content-Length: 361
 Content-Version: 1
-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"
+Link: <http://packages.example.com/mona/LinkedList/1.1.1/Package.swift?swift-version=4>; rel="alternate"; filename="[email protected]"; swift-tools-version="4.0",
+      <http://packages.example.com/mona/LinkedList/1.1.1/Package.swift?swift-version=4.2>; rel="alternate"; filename="[email protected]"; swift-tools-version="4.0"
 
 // swift-tools-version:5.0
 import PackageDescription
@@ -536,14 +539,23 @@ the name of the manifest file
 It is RECOMMENDED for clients and servers to support
 caching as described by [RFC 7234].
 
-A server SHOULD include `Link` header fields with the `alternate` relation type
-for each additional file in the release's source archive
+A server SHOULD include a `Link` header field
+with a value for each version-specific package manifest file
+in the release's source archive,
 whose filename matches the following regular expression pattern:
 
 ```regexp
-\APackage(?:@swift-\d+(?:\.\d+){0,2})?.swift\z
+\APackage@swift-(\d+)(?:\.(\d+))?(?:\.(\d+))?.swift\z
 ```
 
+Each link value SHOULD have the `alternative` relation type,
+a `filename` attribute set to the version-specific package manifest filename
+(for example, `[email protected]`), and
+a `swift-tools-version` attribute set to the [Swift tools version]
+specified by the package manifest file
+(for example, `4.0` for a manifest beginning with the comment
+`// swift-tools-version:4.0`).
+
 #### 4.3.1. swift-version query parameter
 
 A client MAY specify a `swift-version` query parameter
@@ -596,14 +608,14 @@ Location: https://packages.example.com/mona/LinkedList/1.1.1/Package.swift
 
 <a name="endpoint-4"></a>
 
-### 4.4. Fetch source archive
+### 4.4. Download source archive
 
 A client MAY send a `GET` request
 for a URI matching the expression `/{scope}/{name}/{version}`
 to retrieve a release's source archive.
-A client SHOULD set the `Accept` header to
+A client SHOULD set the `Accept` header with the value
 `application/vnd.swift.registry.v1+zip`
-and SHOULD append the `.zip` extension to the requested path.
+and MUST append the `.zip` extension to the requested path.
 
 ```http
 GET /mona/LinkedList/1.1.1.zip HTTP/1.1
@@ -661,31 +673,45 @@ as described by [RFC 6249].
 A client MAY use this information
 to determine its preferred strategy for downloading.
 
-A server that indexes but doesn't host packages
-MAY respond with a status code of `303` (See Other)
-and redirect to a hosted package archive if one is available.
+A server MAY respond with a status code of `303` (See Other)
+to redirect the client to download the source archive from another host.
+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.
+
+For example,
+a server redirects the client to download from
+a content delivery network (CDN) using a signed URL:
 
 ```http
 HTTP/1.1 303 See Other
-Content-Version: 1
+Location: https://example.cdn.com/LinkedList-1.1.1.zip?key=XXXXXXXXXXXXXXXXX
+```
+
+```http
+GET /LinkedList-1.1.1.zip?key=XXXXXXXXXXXXXXXXX HTTP/1.1
+Host: example.cdn.com
+Accept: application/vnd.swift.registry.v1+zip
+```
+
+```http
+HTTP/1.1 200 OK
+Accept-Ranges: bytes
+Cache-Control: public, immutable
+Content-Type: application/zip
+Content-Disposition: attachment; filename="LinkedList-1.1.1.zip"
 Content-Length: 2048
+Content-Version: 1
 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
 
 A client MAY send a `GET` request
 for a URI matching the expression `/identifiers{?url}`
 to retrieve package identifiers associated with a particular URL.
-A client SHOULD set the `Accept` header to
+A client SHOULD set the `Accept` header with the value
 `application/vnd.swift.registry.v1+json`.
 
 ```http
@@ -737,16 +763,13 @@ caching as described by [RFC 7234].
 * [RFC 7807]: Problem Details for HTTP APIs
 * [RFC 8288]: Web Linking
 * [SemVer]: Semantic Versioning
-* [UAX15]: Unicode Technical Report #15: Unicode Normalization Forms
-* [UAX18]: Unicode Technical Report #18: Unicode Regular Expressions
-* [UAX31]: Unicode Technical Report #31: Unicode Identifier and Pattern Syntax
 
 ## 6. Informative References
 
 * [BCP 13] Media Type Specifications and Registration Procedures
 * [RFC 6749]: The OAuth 2.0 Authorization Framework
 * [RFC 8446]: The Transport Layer Security (TLS) Protocol Version 1.3
-* [UAX36]: Unicode Technical Report #36: Unicode Security Considerations
+* [RFC 8631]: Link Relation Types for Web Services
 * [JSON-LD]: A JSON-based Serialization for Linked Data
 * [Schema.org]: A shared vocabulary for structured data.
 * [OAS]: OpenAPI Specification
@@ -1175,10 +1198,7 @@ components:
 [RFC 7807]: https://tools.ietf.org/html/rfc7807 "Problem Details for HTTP APIs"
 [RFC 8288]: https://tools.ietf.org/html/rfc8288 "Web Linking"
 [RFC 8446]: https://tools.ietf.org/html/rfc8446 "The Transport Layer Security (TLS) Protocol Version 1.3"
-[UAX15]: http://www.unicode.org/reports/tr15/ "Unicode Technical Report #15: Unicode Normalization Forms"
-[UAX18]: http://www.unicode.org/reports/tr18/ "Unicode Technical Report #18: Unicode Regular Expressions"
-[UAX31]: http://www.unicode.org/reports/tr31/ "Unicode Technical Report #31: Unicode Identifier and Pattern Syntax"
-[UAX36]: http://www.unicode.org/reports/tr36/ "Unicode Technical Report #36: Unicode Security Considerations"
+[RFC 8631]: https://tools.ietf.org/html/rfc8631 "Link Relation Types for Web Services"
 [IANA Link Relations]: https://www.iana.org/assignments/link-relations/link-relations.xhtml
 [JSON-LD]: https://w3c.github.io/json-ld-syntax/ "JSON-LD 1.1: A JSON-based Serialization for Linked Data"
 [SemVer]: https://semver.org/ "Semantic Versioning"
@@ -1196,3 +1216,4 @@ components:
 [offline cache]: https://yarnpkg.com/features/offline-cache "Offline Cache | Yarn - Package Manager"
 [XCFramework]: https://developer.apple.com/videos/play/wwdc2019/416/ "WWDC 2019 Session 416: Binary Frameworks in Swift"
 [SE-0272]: https://github.com/apple/swift-evolution/blob/master/proposals/0272-swiftpm-binary-dependencies.md "Package Manager Binary Dependencies"
+[Swift tools version]: https://github.com/apple/swift-package-manager/blob/9b9bed7eaf0f38eeccd0d8ca06ae08f6689d1c3f/Documentation/Usage.md#swift-tools-version-specification "Swift Tools Version Specification"