Skip to content

Update Registry documentation according to SE-0292 amendment #3624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Sep 15, 2021
Merged

Update Registry documentation according to SE-0292 amendment #3624

Changes from 3 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
5e2b7ac
Update Registry.md
mattt Jul 20, 2021
aa5e65b
Add example of redirecting to CDN
mattt Jul 22, 2021
ec63004
Update example problem description
mattt Jul 22, 2021
9cb9d87
Amend rules for package names
mattt Jul 28, 2021
dfb2c75
Update Documentation/Registry.md
mattt Jul 28, 2021
8c4ca49
Copy editing
mattt Aug 3, 2021
028b5fb
Link headers for version-specific manifests should include swift-tool…
mattt Aug 3, 2021
22e6846
Add --prefix argument to archive-source command
mattt Aug 4, 2021
362099a
Restructure response to GET /{scope}/{name}/{version}
mattt Aug 7, 2021
f8993de
A release must not have duplicate resources for a given (name, type)
mattt Aug 10, 2021
f374921
Add missing .zip extension to URI path expression
mattt Aug 24, 2021
3fb0de4
Update Documentation/Registry.md
mattt Sep 10, 2021
d2b78f7
Revert "Add --prefix argument to archive-source command"
mattt Sep 15, 2021
028242f
Update regular expression pattern for name in OpenAPI spec
mattt Sep 15, 2021
df82ce2
Merge branch 'main' into mattt-amend-se-0292
mattt Sep 15, 2021
223853c
Formatting
mattt Sep 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 43 additions & 35 deletions Documentation/Registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -109,7 +105,7 @@ Content-Type: application/problem+json
Content-Language: en

{
"detail": "tag '2.0.0' not found"
"detail": "release not found"
}
```

Expand Down Expand Up @@ -256,19 +252,15 @@ 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.
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-Z\d_.-]{1,100}\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 scopes are case-insensitive
(for example, `LinkedList` ≍ `LINKEDLIST`).

## 4. Endpoints

Expand All @@ -285,6 +277,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>
Expand Down Expand Up @@ -506,8 +506,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",
<http://packages.example.com/mona/LinkedList/1.1.1/Package.swift?swift-version=4.2>; rel="alternate"

// swift-tools-version:5.0
import PackageDescription
Expand Down Expand Up @@ -661,23 +661,37 @@ 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
Expand Down Expand Up @@ -737,16 +751,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
Expand Down Expand Up @@ -1175,10 +1186,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"
Expand Down