Module org.elasticsearch.server
Package org.elasticsearch

Record Class TransportVersion

java.lang.Object
java.lang.Record
org.elasticsearch.TransportVersion
All Implemented Interfaces:
Comparable<TransportVersion>
public record TransportVersion(int id) extends Record implements Comparable<TransportVersion>
Represents the version of the wire protocol used to communicate between ES nodes.

Prior to 8.8.0, the release Version was used everywhere. This class separates the wire protocol version from the release version.

Each transport version constant has an id number, which for versions prior to 8.9.0 is the same as the release version for backwards compatibility. In 8.9.0 this is changed to an incrementing number, disconnected from the release version.

Each version constant has a unique id string. This is not actually used in the binary protocol, but is there to ensure each protocol version is only added to the source file once. This string needs to be unique (normally a UUID, but can be any other unique nonempty string). If two concurrent PRs add the same transport version, the different unique ids cause a git conflict, ensuring the second PR to be merged must be updated with the next free version first. Without the unique id string, git will happily merge the two versions together, resulting in the same transport version being used across multiple commits, causing problems when you try to upgrade between those two merged commits.

Version compatibility

The earliest compatible version is hardcoded in the MINIMUM_COMPATIBLE field. Previously, this was dynamically calculated from the major/minor versions of Version, but TransportVersion does not have separate major/minor version numbers. So the minimum compatible version is hard-coded as the transport version used by the highest minor release of the previous major version. MINIMUM_COMPATIBLE should be updated appropriately whenever a major release happens.

The earliest CCS compatible version is hardcoded at MINIMUM_CCS_VERSION, as the transport version used by the previous minor release. This should be updated appropriately whenever a minor release happens.

Adding a new version

A new transport version should be added every time a change is made to the serialization protocol of one or more classes. Each transport version should only be used in a single merged commit (apart from BwC versions copied from Version).

To add a new transport version, add a new constant at the bottom of the list that is one greater than the current highest version, ensure it has a unique id, and update the TransportVersion.CurrentHolder.CURRENT constant to point to the new version.

Reverting a transport version

If you revert a commit with a transport version change, you must ensure there is a new transport version representing the reverted change. Do not let the transport version go backwards, it must always be incremented.