Rectify and document our versioning system

[hug-dev]

We use three different versions in Parsec:

1. The wire protocol version
2. The Parsec service version
3. The provider version

The wire protocol version

It describes the version of the wire protocol itself: what are the different fields of requests and responses. It is needed to parse request and response headers.
The wire protocol might change in the future.
The Ping operation returns the highest wire protocol version supported by the service.
Clients need to perform a bootstrapping sequence if they want to switch to a higher wire protocol version:

1. Client send Ping using wire protocol version 1.0
2. Service answer with highest wire protocol version available x.y
3. Client now knows that it can use wire protocol version x.y for further request.

The response are made by the service using the same wire protocol version than the request it was sent so that client can parse them.

The four first fields of the wire protocol: magic number, header size, version major and version minor will never change for requests and responses.

If a client sends a request with a wire protocol version strictly higher than the highest one supported by the service, a response status VersionTooBig will be sent back as an error.

Actions to take

• Make sure that the wire protocol version system is documented properly and is consistent across all of our documentation
• Add in the client library guide explanation about how the bootstrapping sequence should be performed.
• Modify the front-end handler to first parse the first four fields, check if the version sent is lower than the highest supported (send back VersionTooBig otherwise) and pass the rest to the appropriate wire protocol version deserializer. We should add the reverse logic on the return journey to serialize the response using the same wire protocol version than the request.

The Parsec service version

This version is returned by the ListProviders operation in the ProviderInfoProto structure of the Core Provider. It represents the implementation version of the whole Parsec service. Everytime something is changed on the Parsec service, this number should be modified using the semantic versioning rules the best way possible. It is a way for clients to check if the Parsec version they are using contains the bug/security vulnerabilities fixes that they need or contains the new features that they want.
To make it easy, this version should be the same as the version field in the Cargo.toml file of the parsec crate.

Actions to take

• Document this in the ListProviders section.
• Should probably add a CHANGELOG page in the documentation describing the changes that each version brings so clients are aware.
• Add the logic in the Core Provider to directly fetch its version from the Cargo.toml file.

The Provider version

Each provider (other than the Core provider) also returns a version as part of the ListProviders operation. This version represents the implementation version of the provider. It is needed if the provider is implemented as a co-server for example as there would be no way then to link the Parsec service version to the provider version.

Actions to take

• Document this in the ListProviders section.
• I propose that for the providers that are statically linked with the Parsec service, their version should be the same as the Parsec service version, that is the same as the Core Provider. It makes sense as they share the same dependencies than the Parsec service.

[paulhowardarm]

This captures the issues well.

A couple of things I think we should really try to make clear in the docs:-

• Our design allows the wire protocol format and version to change, but we don't expect this to happen often, and it may not happen at all.
• The wire protocol version number is not the means of finding out the level of support for specific operations in the API. We don't have a model where a client needs to ask the version number in order to find out whether an operation is supported. Version numbers are nothing to do with the API. Clients should call ListOpcodes to find out whether an operation is supported on a per-provider basis.

The "service version" is really only a special case of the provider version. In the docs, it might be a good idea to explain how provider versioning works to begin with, and then indicate that the core provider represents the overall service.

Also, out-of-process co-services are not the only reason why providers need independent versions. This could happen whenever a provider is an independent binary. For instance, it could be a dynamic library.

We will need to make sure it is very clear that provider/service versions and wire protocol versions are totally unrelated. The provider/service versions are implementation versions, whereas the wire protocol version is an interface version.

Lastly, it might be worth a specific statement to say that individual opcode interfaces are not versioned. We use the open/closed principle here. (I think there are words to this effect in the "general principles" section of the API docs, but there can't be harm in repeating them elsewhere). Once an opcode is introduced, its interface is defined and remains the same forever. If we need to modify the interface, we introduce a new opcode with the new signature.

[hug-dev]

Resolved by:

• changes in the book
• changes in Parsec Fix the handling of versioning #110