Table of Contents
Description
The handshake is a special protobuf message 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 handshake message. 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 handshake 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 the Handshake, 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.
NewConnectionHandshake
This is the initial handshake request message. It identifies the protocol version and must be the first message sent on the connection.
NewConnectionHandshake | |||
Field Name | Data type | Description | Mandatory? |
---|---|---|---|
majorVersion | fixed32 | The major version of the client's protocol | Y |
minorVersion | fixed32 | The minor version of the client's protocol | Y |
HandshakeAcknowledgement
If the server sends back a response to the client (cache servers will do so, locators implementing the v1 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).
HandshakeAcknowledgement | |||
Field Name | Data type | Description | Mandatory? |
---|---|---|---|
serverMajorVersion | int32 | The major version of the servers protocol | Y |
serverMinorVersion | int32 | The minor version of the server's protocol | Y |
handshakePassed | boolean | Whether the server is able to communicate with the client's protocol version | Y |