Amend SE-0292

[mattt]

Based on our work implementing the specification and discussion with stakeholders, there are a few changes we'd like to make to SE-0292:

• Package Name: Our original plan was to use the name field in a package manifest to denote the package's name. However, we've come to see this as a bad design decision for several reasons:
  1. It burdens the registry with a requirement to invoke the Swift toolchain to parse the Package manifest
  2. It creates competing sources of truth between the {name} parameter in the HTTP request and the declared name
  3. It causes confusion among package consumers and maintainers, who may not be aware of the package's declared name, nor understand the distinction between that and the source repository name
     We now propose to migrate existing packages according to their repository name, and have updated the naming rules accordingly. Notably, the use of dashes (-) are now supported.
• archive-source behavior: We propose that swift package archive-source subcommand should be equivalent to git-archive with entries prefixed by output name.
• Redirection: The current guidance to treat forwarding headers as authoritative is (as far as I can tell) unprecedented and possibly out-of-spec for HTTP. Our understanding of the feedback in Incorporate feedback from 2nd review of SE-0292 #1319 is that the motivation for this change was to ensure that proxying services are supported. Conventional HTTP redirects support this use case without any special accommodations.
• Web Service Description: Clients should be able to get information about supported endpoints by sending OPTIONS * request to the server.
• Security: Added discussion about the potential attack vector created by working with source archives. This is mostly a reminder that our client implementation should validate Zip files before unarchiving (e.g. reject anything with nested Zip files or entries with relative paths)
• Version-specific manifest link relations: To improve client performance when resolving packages with version-specific manifests, the response to GET /{scope}/{name}/Package.swift now includes swift-tool-version and filename attributes for each version-specific manifest Link header value.
• Update configuration directory: enhance configuraiton for dependencies mirrors swift-package-manager#3670 changes the shared and local configuration directory from .swiftpm/config to .swiftpm/configuration; this PR updates accordingly
• Errata
  • Add missing path components to Link header in example response (thanks, @yim-lee!)
  • Update example problem details response in section 3.3

Corresponding changes to the registry service specification can be found at swiftlang/swift-package-manager#3624

[tomerd]

@mattt @yim-lee should we wait before merging these PRs to see if there are further amendments we need to make and then do all in one go?

[mattt]

@tomerd I don't have anything else to add, so I'd be happy to merge these as soon as we reach a consensus on these changes.

[tomerd]

Our understanding of the feedback in Incorporate feedback from 2nd review of SE-0292 #1319 is that the motivation for this change was to ensure that proxying services are supported. Conventional HTTP redirects support this use case without any special accommodations.

@mattt Would it be helpful to explicitly document what you have in mind for "Conventional HTTP redirects" so its clear how redirecting proxies are expected to work in this context?

[mattt]

@mattt Would it be helpful to explicitly document what you have in mind for "Conventional HTTP redirects" so its clear how redirecting proxies are expected to work in this context?

Sure, I just added an example in the specification of how redirection works to proxy a download to another host: swiftlang/swift-package-manager@aa5e65b.

[mmarston]

Our original plan was to use the name field in a package manifest to denote the package's name. However, we've come to see this as a bad design decision...

Does this mean there is no longer any correlation between the name in the manifest and the package's name in a package registry? I realize that one of the reasons for the change is to avoid confusion. But doesn't it seem like having a different package name in the manifest than in the registry could be a source of confusion?

It burdens the registry with a requirement to invoke the Swift toolchain to parse the Package manifest

I appreciate the change in this regard.

[mattt]

Our original plan was to use the name field in a package manifest to denote the package's name. However, we've come to see this as a bad design decision...

Does this mean there is no longer any correlation between the name in the manifest and the package's name in a package registry?

Yes, that's correct.

I realize that one of the reasons for the change is to avoid confusion. But doesn't it seem like having a different package name in the manifest than in the registry could be a source of confusion?

The name field in the package manifest has been a source of confusion since it was introduced. Currently, repo-based dependencies are identified by the last path component of their URL. This creates a problem if two distinct repos have the same name (e.g. github.com/A/Foo and github.com/B/Foo). The name field was added to provide a unique label to the package node in the dependency graph. With the namespaced package identity scheme introduced here, we no longer need the name field, and will likely move to deprecate and remove it in future versions.

After working through the original proposal, we determined that the idea of using the name field is significantly more difficult and confusing than what we're proposing in this amendment. We believe it's the best option available to us going forward.

[mattt]

@robertlacroix What we have right now with ZipArchiver delegates to unzip:

https://github.com/apple/swift-tools-support-core/blob/435a2708a6e486d69ea7d7aaa3f4ad243bc3b408/Sources/TSCUtility/Archiver.swift#L65

Right now, we're using this only for user-specified source files in binary targets. Do you think we should do anything differently in support of archives sent from the package registry?