Record Class TransformConfigVersion

java.lang.Object
java.lang.Record
org.elasticsearch.xpack.core.transform.TransformConfigVersion
All Implemented Interfaces:
Comparable<TransformConfigVersion>, VersionId<TransformConfigVersion>, org.elasticsearch.xcontent.ToXContent, org.elasticsearch.xcontent.ToXContentFragment

public record TransformConfigVersion(int id) extends Record implements VersionId<TransformConfigVersion>, org.elasticsearch.xcontent.ToXContentFragment
The version number associated with various Transform features. This class is needed in addition to TransportVersion because transport version cannot be persisted in stored documents or cluster state metadata. Hence, this class is designed to be persisted in human-readable format, and indicate the age of that state or config. In addition, we want the written form of TransformConfigVersion version numbers to be parseable by the Version class so that in mixed version clusters during upgrades the old nodes won't throw exceptions when parsing these new versions.

Prior to 8.10.0, the release Version was used everywhere. This class separates the Transform config format version from the running node version.

Each Transform config version constant has an id number, which for versions prior to 8.10.0 is the same as the release version for backwards compatibility. In 8.10.0 this is changed to an incrementing number, disconnected from the release version, starting at 10000099. This format is chosen for best compatibility with old node versions. *

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 Transform config 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 Transform config version being used across multiple commits, causing problems when you try to upgrade between those two merged commits.

Version compatibility

The earliest version is hardcoded in the FIRST_TRANSFORM_VERSION field. This cannot be dynamically calculated from the major/minor versions of Version, because TransformConfigVersion does not have separate major/minor version numbers. So the minimum version is simply hard-coded as the earliest version where Transform existed (7.2.0).

Adding a new version

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

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

Reverting a Transform config version

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