Description 

The version identification is a special protobuf exchange which doesn't follow the normal Message structure used by the other operations.  This allows the rest of the protocol some flexibility to grow and change without breaking the versioning messages.  It also gives the server side code a very recognizable message to look for, which allows it to recognize incoming protobuf connections when using a port which may receive multiple connection formats.  The version identification must be the first communication sent across any incoming protobuf connection.  It serves to identify the protocol version being used by the client to ensure that the server is able to communicate.

Versioning

The purpose of this exchange, aside from identifying the connection as a protobuf connection, is to identify the version of the protocol in use by the client (and potentially by the server to the client).  Note that this is the version of the protocol files in use by the client, and shouldn't be confused with the version of the underlying protobuf spec (which should always be protobuf V3).  The version consists of both a major and minor version number.  The handshake.proto file contains enums for the version fields where MajorVerions.CURRENT_MAJOR_VERSION and MinorVersions.CURRENT_MINOR_VERSION will be the version implemented by this package of proto files.

NewConnectionClientVersion

This is the initial client version message.  It identifies the protocol version and must be the first message sent on the connection.

NewConnectionClientVersion
Field NameData typeDescriptionMandatory?
majorVersionfixed32The major version of the client's protocolY
minorVersionfixed32The minor version of the client's protocol

VersionAcknowledgement

If the server sends back a response to the client (cache servers will do so, locators implementing the v1.x version of the protocol will not), it will be this type of message.  Note that the server is not allowed to respond with an ErrorResponse message as the formal of that message may vary in different versions.  The server will populate this message with its protocol version and will also indicate whether the server can communicate with the client's version.  If it is unable to communicate with the client version, it is expected to close the connection after sending this response (locators will simply close the connection if they are unable to communicate with the client).

VersionAcknowledgement
Field NameData typeDescriptionMandatory?
serverMajorVersionint32The major version of the servers protocolY
serverMinorVersionint32The minor version of the server's protocolY
versionAcceptedbooleanWhether the server is able to communicate with the client's protocol versionY
  • No labels