Knowing when the client version is different from the agent version

[CMCDragonkai]

Specification

While using the NixOS installed polykey I realised that my PK client version is not the same as the agent version that I was connecting to.

The agent version is was running from staging branch.

So right now there are 2 main ways to ask about the version:

polykey --version
polykey agent status

The first is asking the local client program's version. It will tell you:

["0.10.0","1.14.0","1","1"]

Which is CLI version, library version, state version, network version.

When connecting to an agent, it will tell you:

version          	1.15.1-1-1
sourceVersion    	1.15.1
stateVersion     	1
networkVersion   	1
versionMetadata  	
  version          	0.13.0
  commitHash       	9ec49bf1efa2fe025bed58574c2c77a3c3eceb7d
  libVersion       	1.15.1-1-1
  libSourceVersion 	1.15.1
  libStateVersion  	1
  libNetworkVersion	1

This is a bit more confusing, the versionMetadata shouldn't be required anymore right? I'm not sure why that's still there... or we should incorporate it into the standard data. I think it had something to do with the testnet mainnet dashboard. We should see if we can reduce the amount of redundancy here.

But anyway... you can see here that it reports the agent's version instead.

There's a few things I'd like to do here:

1. I want to have a standard "version" string that we can make use of. That I believe to have sufficient coverage we would need to do: Program-Library-State-Network. However the library itself doesn't know what the program version is. Only the program does. I believe the program needs to inject its version into agent status command... that's the only way it works. Therefore should see something like: 0.13.0-1.15.1-1-1. The problem is that we don't distinguish between client program and agent program. So...
2. We need to simplify can clarify the agent status output here... I propose given that the version metadata is loaded from the outside of the source during the build process to get the commit hash, we should see something like:

agentVersion     0.13.0-1.15.1-1-1
agentCommitHash  ...
clientVersion    0.10.0-1.14.0-1-1
clientCommitHash ...

I think that's sufficient, we don't need all that extra stuff.

Then the agent status will be alot easier to parse and it won't be super long with lots of unnecessary detail.

We will need to update the testnet and mainnet dashboards to compensate for these changes.

The key thing is that during debugging, when people have a problem, we can now know if it is due to the client having a different version from the agent.

Also another thing is that polykey --version looks weird too. But I recognise, part of the reason is due to the prerelease identifiers which support 1.2.0-alpha.0. Which means we have ambiguity like:

0.13.0-alpha.1-1.15.1-beta.0-1-1

But I think the ambiguity can technically be resolved with some regular expression. But it does become more difficult to parse.

So as in #172, we can do something like this instead, preferring the JSON serialisation of the array.

["0.13.0-alpha.1","1.15.1-beta.0","1","1"]

To be used for both agent status output and for polykey --version.

agentVersion     ["0.13.0","1.15.1","1","1"]
agentCommitHash  ...
clientVersion    ["0.10.0","1.14.0","1","1"]
clientCommitHash ...

That makes it easier to compare... etc.

Additional Context

• Version Metadata Standardization #121

Tasks

1. Update the version outputs for agent status.
2. Makes sure that agent status actually shows both agentVersion and clientVersion.
3. Simplify the version metadata fields... I think it could just show the commitHash or incorporate into the top level fields

[linear]

ENG-454 Knowing when the client version is different from the agent version

[CMCDragonkai]

This can be a common occurrence internally in the team due to system installation and home installation, that's why I realised that it doesn't make sense to have polykey installed on a system level for operator platforms in our nixpkgs-matrix-private. It's better to instead be a home manager installed thing and solely that to avoid confusion between system and user-level packages/services.

@brynblack

https://github.com/MatrixAI/nixpkgs-matrix-private/pull/16

[aryanjassal]

I am not a big fan of the version string formatting. We, as the developers, know how to parse the output, but an end user might not. The numbers would mean nothing to them. Which is why I propose changing the output of polykey -V or polykey --version to a multi-line format, similar to how Neovim has handled this.

$ nvim --version   
NVIM v0.10.2
Build type: Release
LuaJIT 2.1.1713773202

For Polykey, it could look like this.

$ polykey --version   
Library v1.10.0-1
Agent v0.14.0
State 1
Network 1

One could argue that the state and network information isn't relevant when the polykey --version command is run, as the user would be expecting the version of the program itself, and not the state the entire Polykey network is in. So, this can be further reduced to this.

$ polykey --version
Library v1.10.0-1
Agent v0.14.0

Then, we can keep the current separation between client and agent and display the version metadata as such.

...
versionMetadata  	
  clientVersion       	1.15.1-1
  clientCommitHash      9ec49bf1efa2fe025bed58574c2c77a3c3eceb7d
  agentVersion       	0.16.1
  agentCommitHash       8eadbca234f9123847fade230a909284bfecebd
  stateVersion  	    1
  networkVersion	    1

If we need this to be a single string, we can explore other ways to separate the different versions than using a JSON representation. These are possible ways to represent the version in a single line, but I believe the version should be more descriptive in this case, as we need to display the versions of up to four different sources.

$ polykey --version
0.16.1 : 1.15.1-1 : 1 : 1

$ polykey --version
0.16.1 | 1.15.1-1 | 1 | 1

Thoughts, @CMCDragonkai @tegefaulkes?

[tegefaulkes]

I get where you're coming from, but I think what we've discussed so far is the best compromise we have for now.

agentVersion     ["0.13.0","1.15.1","1","1"]
agentCommitHash  ...
clientVersion    ["0.10.0","1.14.0","1","1"]
clientCommitHash ...

So lets stick with this.

[CMCDragonkai]

I think we should have a warning occur whenever a client connects to the agent with a different versions.

Different versions actually to trigger checks:

• State version out of date requires a migration - with respect to the server side
• Network version out of date should actually cause the client to fail to connect - there should be an option to "force" connection though...
• Library version out of date is a warning - especially cause client call might be in sync with the expected behaviour of the server handlers
• Program version out of date is not really a problem