Stability: Communication with clients (operation contracts)

[hug-dev]

Definition: The behaviour of operations must remain the same for all versions of the service.
Enforcement: There is a defined behaviour for all operations that is respected.

Enforcement Check

The behaviour of operations are written in the contracts. Those, as part of the Wire Protocol, are stable by design and will not change with Parsec versions. Only new contracts can be created.

All contracts should be reviewed to make sure the behaviour is correctly explained.

Testing

The testing here is very similar as of #388 but with a bigger focus on the "behaviour". For example make sure that the policy is respected. This accross different versions of Parsec/Client.

[hug-dev]

Some of this was discussed in the community meeting, see here.

[hug-dev]

The title is only referring to "operation contracts" but I think we should cover the behaviour of the whole Wire Protocol. By behaviour I mean the expectations that are put in writing but can not be checked in a straightforward way by verifying the operation result.
For example for the "header" tests:

• the "Provider" field does target the intended provider (when provider ID is found via ListProviders)
• the "opcode" field does trigger the correct operation (checking opcodes do not change)
• the "auth type" field has an effect on the authenticator used (auth ID do not change)
• the "status" field yield the expected number

For the operations:

• the key policy is respected when generating a key and using it
• "The key_type field of attributes can not be an asymmetric public key."
• a destroyed key can not be used again
• the priority of ListProviders is respected
• etc

I believe these tests could be contained in the same set as #388

[hug-dev]

Note that the contract should still be respected even for keys stored with an old version of the Parsec service. For example for key policy, if the policy is respected with a key with Parsec version A, it should still be respected on the same key with Parsec version B (when only the binary is changed from A to B).

[hug-dev]

To check that current PRs still work with older clients, we could checkout the e2e_tests folder at some points in the past and make sure the tests still work in the CI.
The other direction, checking that current PRs on clients still work with older versions of the service, can be the responsability of the clients to test.

edit: a good alternative is also to always try to use the oldest Parsec Rust Client in the e2e_tests crate.

[hug-dev]

I found a hacky way to only be able to download the e2e_tests crate out of Parsec GitHub repository, at a specific version:

Check which svn revision to use with:

svn log https://github.com/parallaxsecond/parsec.git/trunk/e2e_tests/Cargo.toml

It's the number after r, for example r233 is the first one.

Download the e2e_tests folder at that specific revision:

svn export -r 233 https://github.com/parallaxsecond/parsec.git/trunk/e2e_tests

And then inside the folder we can do cargo test ...!

We can choose a specific revision that is old enough.

edit: we will need to add svn on the Docker image if not already there 😬

[hug-dev]

Reminder to update the test list in the book with those new added tests.