Skip to content

Commit d8f7a4b

Browse files
yim-leeyim-lee
authored
Update registry service spec per SE-0391 (#6372)
https://github.com/apple/swift-evolution/blob/main/proposals/0391-package-registry-publish.md
1 parent 29e34d6 commit d8f7a4b

File tree

1 file changed

+93
-81
lines changed

1 file changed

+93
-81
lines changed

‎Documentation/Registry.md

Lines changed: 93 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,12 @@
2121
- [4.4. Download source archive](#44-download-source-archive)
2222
- [4.4.1. Integrity verification](#441-integrity-verification)
2323
- [4.4.2. Download locations](#442-download-locations)
24+
- [4.4.3. Signature validation](#443-signature-validation)
2425
- [4.5. Lookup package identifiers registered for a URL](#45-lookup-package-identifiers-registered-for-a-url)
26+
- [4.5.1 URL to package identifier mappings](#451-url-to-package-identifier-mappings)
2527
- [4.6. Create a package release](#46-create-a-package-release)
2628
- [4.6.1. Source archive](#461-source-archive)
2729
- [4.6.2. Package release metadata](#462-package-release-metadata)
28-
- [4.6.2.1. Reserved metadata keys](#4621-reserved-metadata-keys)
2930
- [4.6.3. Synchronous and asynchronous publication](#463-synchronous-and-asynchronous-publication)
3031
- [4.6.3.1. Synchronous publication](#4631-synchronous-publication)
3132
- [4.6.3.2. Asynchronous publication](#4632-asynchronous-publication)
@@ -458,7 +459,11 @@ Link: <https://packages.example.com/mona/LinkedList/1.1.1>; rel="latest-version"
458459
{
459460
"name": "source-archive",
460461
"type": "application/zip",
461-
"checksum": "a2ac54cf25fbc1ad0028f03f0aa4b96833b83bb05a14e510892bb27dea4dc812"
462+
"checksum": "a2ac54cf25fbc1ad0028f03f0aa4b96833b83bb05a14e510892bb27dea4dc812",
463+
"signing": {
464+
"signatureBase64Encoded": "l1TdTeIuGdNsO1FQ0ptD64F5nSSOsQ5WzhM6/7KsHRuLHfTsggnyIWr0DxMcBj5F40zfplwntXAgS0ynlqvlFw==",
465+
"signatureFormat": "cms-1.0.0"
466+
}
462467
}
463468
],
464469
"metadata": { ... }
@@ -489,11 +494,19 @@ MAY correspond to the requested release.
489494

490495
Each element in the `resources` array is a JSON object with the following keys:
491496

492-
| Key | Type | Description |
493-
| ---------- | ------- | ------------------------------------------------------------------- |
494-
| `name` | String | The name of the resource. |
495-
| `type` | String | The content type of the resource. |
496-
| `checksum` | String | A hexadecimal representation of the SHA256 digest for the resource. |
497+
| Key | Type | Description |
498+
| ---------- | ------- | -------------------------------------------------------------------------- |
499+
| `name` | String | The name of the resource. |
500+
| `type` | String | The content type of the resource. |
501+
| `checksum` | String | A hexadecimal representation of the SHA256 digest for the resource. |
502+
| `signing` | Object | Information about the signature. Required only if the resource is signed. |
503+
504+
The `signing` JSON object contains these keys:
505+
506+
| Key | Type | Description |
507+
| ------------------------ | ------- | ------------------------------------------------- |
508+
| `signatureBase64Encoded` | String | The resource's signature, base64 encoded. |
509+
| `signatureFormat` | String | The signature format. (e.g., `cms-1.0.0`) |
497510

498511
A resource object SHOULD have one of the following combinations of
499512
`name` and `type` values:
@@ -507,41 +520,12 @@ with a given combination of `name` and `type` values.
507520

508521
#### 4.2.2. Package release metadata standards
509522

510-
A server MAY include metadata in its package release response.
511-
It is RECOMMENDED that package metadata be represented in [JSON-LD]
512-
according to a structured data standard.
513-
For example,
514-
this response using the [Schema.org] [SoftwareSourceCode] vocabulary:
515-
516-
```jsonc
517-
{
518-
"id": "mona.LinkedList",
519-
"version": "1.1.1",
520-
"resources": [ ... ],
521-
"metadata": {
522-
"@context": ["http://schema.org/"],
523-
"@type": "SoftwareSourceCode",
524-
"name": "LinkedList",
525-
"description": "One thing links to another.",
526-
"keywords": ["data-structure", "collection"],
527-
"version": "1.1.1",
528-
"codeRepository": "https://github.com/mona/LinkedList",
529-
"license": "https://www.apache.org/licenses/LICENSE-2.0",
530-
"programmingLanguage": {
531-
"@type": "ComputerLanguage",
532-
"name": "Swift",
533-
"url": "https://swift.org"
534-
},
535-
"author": {
536-
"@type": "Person",
537-
"@id": "https://example.com/mona",
538-
"givenName": "Mona",
539-
"middleName": "Lisa",
540-
"familyName": "Octocat"
541-
}
542-
}
543-
}
544-
```
523+
SE-391 defines the [JSON schema] for package release metadata that
524+
gets submitted as part of the ["create a package release"](#endpoint-6)
525+
request. A server MAY allow and/or populate additional metadata by
526+
expanding the schema. The `metadata` key in the
527+
["fetch information about a package release "](#endpoint-2) API response
528+
will hold the user-provided as well as the server populated metadata.
545529

546530
<a name="endpoint-3"></a>
547531

@@ -704,6 +688,8 @@ Content-Length: 2048
704688
Content-Version: 1
705689
Digest: sha-256=oqxUzyX7wa0AKPA/CqS5aDO4O7BaFOUQiSuyfepNyBI=
706690
Link: <https://mirror-japanwest.example.com/mona-LinkedList-1.1.1.zip>; rel=duplicate; geo=jp; pri=10; type="application/zip"
691+
X-Swift-Package-Signature-Format: cms-1.0.0
692+
X-Swift-Package-Signature: l1TdTeIuGdNsO1FQ0ptD64F5nSSOsQ5WzhM6/7KsHRuLHfTsggnyIWr0DxMcBj5F40zfplwntXAgS0ynlqvlFw==
707693
```
708694

709695
A server MUST respond with a `Content-Length` header
@@ -727,6 +713,10 @@ It is RECOMMENDED for clients and servers to support
727713
range requests as described by [RFC 7233]
728714
and caching as described by [RFC 7234].
729715

716+
If a release is signed, a server MUST include
717+
`X-Swift-Package-Signature-Format` and `X-Swift-Package-Signature`
718+
headers in the response.
719+
730720
#### 4.4.1. Integrity verification
731721

732722
A client MUST verify the integrity of a downloaded source archive using
@@ -779,6 +769,14 @@ Content-Version: 1
779769
Digest: sha-256=a2ac54cf25fbc1ad0028f03f0aa4b96833b83bb05a14e510892bb27dea4dc812
780770
```
781771

772+
#### 4.4.3. Signature validation
773+
774+
A client MUST validate the signature of a signed archive
775+
according to the signature format and configuration. Signing
776+
information can alternatively be found in the associated
777+
`source-archive` resource in the response to `GET /{scope}/{name}/{version}`,
778+
as described in [4.2.1](#421-package-release-resources).
779+
782780
<a name="endpoint-5"></a>
783781

784782
### 4.5. Lookup package identifiers registered for a URL
@@ -825,6 +823,20 @@ nested at a top-level `identifiers` key.
825823
It is RECOMMENDED for clients and servers to support
826824
caching as described by [RFC 7234].
827825

826+
#### 4.5.1 URL to package identifier mappings
827+
828+
As part of the [package release metadata](#422-package-release-metadata-standards)
829+
JSON object, the `repositoryURLs` array can be used to specify
830+
URLs associated with a package identifier. This is one way
831+
through which a server can obtain URL to package identifier
832+
mappings for this API.
833+
834+
A server MAY choose other mechanism(s) for package authors
835+
to specify these mappings.
836+
837+
A server SHOULD validate the package author's ownership claim
838+
on the corresponding repository.
839+
828840
<a name="endpoint-6"></a>
829841

830842
### 4.6. Create a package release
@@ -836,10 +848,12 @@ to publish a release of a package.
836848
A client MUST provide a body encoded as multipart form data
837849
with the following sections:
838850

839-
| Key | Content-Type | Description | Requirement Level |
840-
| ----------------- | ------------------ | ----------------------------------------- | ----------------- |
841-
| `source-archive` | `application/zip` | The source archive of the package. | REQUIRED |
842-
| `metadata` | `application/json` | Additional information about the release. | OPTIONAL |
851+
| Key | Content-Type | Description | Requirement Level |
852+
| -------------------------- | -------------------------- | ----------------------------------------- | ----------------- |
853+
| `source-archive` | `application/zip` | The source archive of the package. | REQUIRED |
854+
| `source-archive-signature` | `application/octet-stream` | The signature of the source archive. | OPTIONAL |
855+
| `metadata` | `application/json` | Additional information about the release. | OPTIONAL |
856+
| `metadata-signature` | `application/octet-stream` | The signature of the metadata. | OPTIONAL |
843857

844858
A client MUST set a `Content-Type` header with the value
845859
`multipart/form-data`. `boundary` can be any string.
@@ -853,13 +867,17 @@ the total size of the body in bytes.
853867
A client SHOULD set the `Accept` header with the value
854868
`application/vnd.swift.registry.v1+json`.
855869

870+
A client MUST set a `X-Swift-Package-Signature-Format` header
871+
with the signature format if the source archive is signed.
872+
856873
```http
857874
PUT /mona/LinkedList/1.1.1 HTTP/1.1
858875
Host: packages.example.com
859876
Accept: application/vnd.swift.registry.v1+json
860877
Content-Type: multipart/form-data;boundary="boundary"
861878
Content-Length: 336
862879
Expect: 100-continue
880+
X-Swift-Package-Signature-Format: cms-1.0.0
863881
864882
--boundary
865883
Content-Disposition: form-data; name="source-archive"
@@ -869,13 +887,29 @@ Content-Transfer-Encoding: base64
869887
870888
gHUFBgAAAAAAAAAAAAAAAAAAAAAAAA==
871889
890+
--boundary
891+
Content-Disposition: form-data; name="source-archive-signature"
892+
Content-Type: application/octet-stream
893+
Content-Length: 88
894+
Content-Transfer-Encoding: base64
895+
896+
l1TdTeIuGdNsO1FQ0ptD64F5nSSOsQ5WzhM6/7KsHRuLHfTsggnyIWr0DxMcBj5F40zfplwntXAgS0ynlqvlFw==
897+
872898
--boundary
873899
Content-Disposition: form-data; name="metadata"
874900
Content-Type: application/json
875901
Content-Transfer-Encoding: quoted-printable
876902
Content-Length: 3
877903
878-
{ }
904+
{ "repositoryURLs": [] }
905+
906+
--boundary
907+
Content-Disposition: form-data; name="metadata-signature"
908+
Content-Type: application/octet-stream
909+
Content-Length: 88
910+
Content-Transfer-Encoding: base64
911+
912+
M6TdTeIuGdNsO1FQ0ptD64F5nSSOsQ5WzhM6/7KsHRuLHfTsggnyIWr0DxMcBj5F40zfplwntXAgS0ynlqvlFw==
879913
880914
```
881915

@@ -1001,46 +1035,31 @@ A client MAY include a multipart section named `metadata`
10011035
containing additional information about the release.
10021036
A client SHOULD set a `Content-Type` header with the value `application/json`
10031037
and a `Content-Length` header with the size of the JSON document in bytes.
1004-
It is RECOMMENDED that package release metadata be represented in [JSON-LD]
1005-
according to a structured data standard,
1006-
as discussed in [4.2.1](#421-package-release-metadata-data-standards).
1038+
The package release metadata MUST be based on the [JSON schema],
1039+
as discussed in [4.2.2](#422-package-release-metadata-standards).
10071040

10081041
```http
10091042
--boundary
10101043
Content-Disposition: form-data; name="metadata"
10111044
Content-Type: application/json
1012-
Content-Length: 620
1045+
Content-Length: 226
10131046
Content-Transfer-Encoding: quoted-printable
10141047
10151048
{
1016-
"@context": ["http://schema.org/"],
1017-
"@type": "SoftwareSourceCode",
1018-
"name": "LinkedList",
10191049
"description": "One thing links to another.",
1020-
"keywords": ["data-structure", "collection"],
1021-
"version": "1.1.1",
1022-
"codeRepository": "https://github.com/mona/LinkedList",
1023-
"license": "https://www.apache.org/licenses/LICENSE-2.0",
1024-
"programmingLanguage": {
1025-
"@type": "ComputerLanguage",
1026-
"name": "Swift",
1027-
"url": "https://swift.org"
1028-
},
1050+
"repositoryURLs": ["https://github.com/mona/LinkedList"],
1051+
"licenseURL": "https://www.apache.org/licenses/LICENSE-2.0",
10291052
"author": {
1030-
"@type": "Person",
1031-
"@id": "https://github.com/mona",
1032-
"givenName": "Mona",
1033-
"middleName": "Lisa",
1034-
"familyName": "Octocat"
1053+
"name": "Mona Lisa Octocat"
10351054
}
10361055
}
10371056
10381057
```
10391058

1040-
If a client doesn't provide a `metadata` section,
1041-
a server MAY populate the metadata for a release.
1042-
A client MAY request that a server not populate metadata automatically
1043-
by sending an empty JSON object (`{}`) as its request body.
1059+
A server MAY allow and/or populate additional metadata for a release.
1060+
1061+
A server MAY make any properties in the [JSON schema] and additional
1062+
metadata it defines required.
10441063

10451064
If a client provides an invalid JSON document,
10461065
the server SHOULD respond with a status code of
@@ -1056,15 +1075,7 @@ Content-Language: en
10561075
{
10571076
"detail": "invalid JSON provided for release metadata"
10581077
}
1059-
```
1060-
1061-
##### 4.6.2.1. Reserved metadata keys
1062-
1063-
These metadata keys have special meanings to the server and should be included if and only if their value satisifies their intended use:
1064-
1065-
| Key | Description | Server Use |
1066-
| ----------------- | ---------------------------------------------------- | -------------------------------------- |
1067-
| `repositoryURLs` | An array of the package's source code repository URLs (e.g., `["https://github.com/mona/LinkedList", "ssh://[email protected]:mona/LinkedList.git"]`). | The mappings between package identifer and repository URL get recorded for the [lookup package identifiers by URL](#endpoint-5) endpoint. |
1078+
```
10681079

10691080
#### 4.6.3. Synchronous and asynchronous publication
10701081

@@ -1734,3 +1745,4 @@ components:
17341745
[XCFramework]: https://developer.apple.com/videos/play/wwdc2019/416/ "WWDC 2019 Session 416: Binary Frameworks in Swift"
17351746
[SE-0272]: https://github.com/apple/swift-evolution/blob/master/proposals/0272-swiftpm-binary-dependencies.md "Package Manager Binary Dependencies"
17361747
[Swift tools version]: https://github.com/apple/swift-package-manager/blob/9b9bed7eaf0f38eeccd0d8ca06ae08f6689d1c3f/Documentation/Usage.md#swift-tools-version-specification "Swift Tools Version Specification"
1748+
[JSON schema]: https://github.com/apple/swift-evolution/blob/main/proposals/0391-package-registry-publish.md#package-release-metadata-standards "JSON schema for package release metadata"

0 commit comments

Comments
 (0)