Semver 2.0.0 protocol support

[yishaigalatzer]

Tracking protocol changes to servers and clients to support backward compatibility of servers with nuget clients that do not support semver 2.0.0.

The goal is that for heterogeneous client environments to be able to see only semver 1.0.0 versions on a server that supports both 2.0.0 and 1.0.0 and thus not breaking the clients and allowing a gradual migration (if at all).

Example of clear examples of such servers: nuget.org, VSTS, myget.

Spec-ing is tracked in https://github.com/NuGet/Home/wiki/Semver-2.0.0-Protocol

[yishaigalatzer]

CC @zjrunner @xavierdecoster @maartenba

[maartenba]

Hasn't the NuGet V3 client always supported SemVer 2.0 since the beginning? (@emgarten ?) If yes, we don't need to change V3 protocol nor registrations/package download URL's.

For older clients targetting the OData feed, there are a few options:

• Not support SemVer 2.0 packages at all on the OData feed. Anyone targeting www.nuget.org/api/v2 would never see the SemVer 2.0 packages. Want to see them? Use the V3 feed.
• Do a selective "hide" of SemVer 2.0 packages, as described in the spec. Either based on User Agent version, or a query string addition/omission. Or by adding a header when requesting data. For OData those are the only options, and header/query string sounds most solid (user agent-based logic is bound to fail).

Now, the spec says anyone pre-3.5 will break with SemVer 2.0 packages, so let's assume we also have to update the V3 feeds.

• For search, can we have the client send an Accept: header, which adds the features it supports? E.g. Accept: application/json+semver1;semver2? That way, search can respond with or without those packages in the search results.
• For registrations, that's a different story. Since these are all static, this would require us to create two copies of all registrations (with and without SemVer 2.0 packages), with a different content type version in the index.json.
• For package downloads, no need to change anything there, as the packages will only be downloaded by clients that have had a response from search or registrations contining the SemVer 2.0 package URL. Can be safely ignored imo.

[emgarten]

Hasn't the NuGet V3 client always supported SemVer 2.0 since the beginning?

Yes, the v3 protocol has had SemVer 2.0.0 support from the start.

It could benefit pre-3.5 clients if SemVer 2.0.0 versions were removed from the registration blobs so that they would not show up as install options in the UI.

PackageBaseAddress is only used by project.json restore, and that has supported SemVer 2.0.0 since 3.1.0 when it was introduced, so that part of v3 wouldn't need to split.

[joelverhagen]

One complication introduced by this SemVerLevel filtering is that the notion of "latest package" is now more complicated. Currently the IsLatest and IsAbsoluteLatest OData properties can be determined without any knowledge of the caller.

I don't know if this is important or not. It looks like currently the client code (both in "install latest" flow and in floating versions) gets the full list of available versions and takes the maximum version rather than looking at the IsLatest or IsAbsoluteLatest properties. Old or 3rd party clients might not do this though.

If we want to make the OData correct with respect to the SemVerLevel query param (exact query param as mentioned in the spec), does this mean that for every package ID there are now two sets of IsLatest and IsAbsoluteLatest versions?

We need to nail this question down before introducing this change to NuGet.Server so that OData results are correct and NuGet.org so that OData and HTML output are correct.

[joelverhagen]

This has been implemented in dev and master of NuGet.Server. It is not yet supported on nuget.org.

This needs client support for OData endpoints and search service. There is already support in V3 via NuGet/NuGet.Client@358f3b5.

[joelverhagen]

/cc @rrelyea, could this be assigned and scheduled as client work?

[maartenba]

This is now supported on www.MyGet.org.

[joelverhagen]

@maartenba, nice! Does semVerLevel default to 1.0.0 when not included in the query string? If I recall this is a change in functional for MyGet? Or did MyGet never support SemVer 2.0.0 in packages?

[maartenba]

Indeed defaulting to 1.0.0. We did have 2.0 but not yet widely used so safe change.

[emgarten]

I believe this is complete on the client side, please reopen if there is more work to do.