diff --git a/docs/protocol.html b/docs/protocol.html index 9a21639dba1..84f4aec4b0d 100644 --- a/docs/protocol.html +++ b/docs/protocol.html @@ -45,11 +45,6 @@
The intention is that clients will support a range of API versions. When communicating with a particular broker, a given client should use the highest API version supported by both and indicate this version in their requests.
-The server will reject requests with a version it does not support, and will always respond to the client with exactly the protocol format it expects based on the version it included in its request. The intended upgrade path is that new features would first be rolled out on the server (with the older clients not making use of them) and then as newer clients are deployed these new features would gradually be taken advantage of.
+The server will reject requests with a version it does not support, and will always respond to the client with exactly the protocol format it expects based on the version it included in its request. The intended upgrade path is that new features would first be rolled out on the server (with the older clients not making use of them) and then as newer clients are deployed these new features would gradually be taken advantage of. Note there is an exceptional case while retrieving supported API versions where the server can respond with a different version.
Note that KIP-482 tagged fields can be added to a request without incrementing the version number. This offers an additional way of evolving the message schema without breaking compatibility. Tagged fields do not take up any space when the field is not set. Therefore, if a field is rarely used, it is more efficient to make it a tagged field than to put it in the mandatory schema. However, tagged fields are ignored by recipients that don't know about them, which could pose a challenge if this is not the behavior that the sender wants. In such cases, a version bump may be more appropriate.
@@ -143,7 +138,13 @@
Kafka protocol requests may take place on an SSL listener before the SSL handshake is finished). If this is considered to
leak information about the broker version a workaround is to use SSL with client authentication which is performed at an
earlier stage of the connection where the ApiVersionRequest
is not available. Also, note that broker versions older
- than 0.10.0.0 do not support this API and will either ignore the request or close connection in response to the request.
ApiVersionsRequest
version is unsupported by the broker (client is ahead), and the broker
+ version is 2.4.0 or greater, then the broker will respond with a version 0 ApiVersionsResponse
+ with the error code set to UNSUPPORTED_VERSION
and the api_versions
+ field populated with the supported version of the ApiVersionsRequest
. It is then up to the client to retry, making
+ another ApiVersionsRequest
using the highest version supported by the client and broker.
+ See KIP-511: Collect and Expose Client's Name and Version in the Brokers