AndrewJSchofield opened a new pull request, #17498: URL: https://github.com/apache/kafka/pull/17498
The Kafka documentation includes a description of the Kafka protocol (https://kafka.apache.org/protocol). This is useful to someone wanting to understand the details of the protocol. However, in the area of tagged fields, the documentation is not helpful. Tagged fields provide a way of supplying optional data in a request or response. Modern requests and responses usually permit tagged fields, although they are relatively rarely used in practice. One RPC in which tagged fields contain important information is the APIVersionsResponse. In v3 and above, the response contains the set of supported and finalised features, which can be used by a client to determine whether a broker supports a feature. This information is carried as tagged fields, but if you read the documentation of the protocol, you would be entirely in the dark. This improvement adds tagged field information into the protocol documentation. Here's an example before the change. Each of the TAG_BUFFER fields is included in the table of fields, even ones for which there are no tagged fields defined.  Here's the same RPC response in which only the TAG_BUFFER which actually has tagged fields defined is in the table, and the tagged field descriptions are included in the table in a sub-table. <img width="997" alt="APIVersionsResponse_after" src="https://github.com/user-attachments/assets/e47c3381-8994-4de9-9469-646c37311520";> This change also indicates which RPC request versions are unstable. ### Committer Checklist (excluded from commit message) - [ ] Verify design and implementation - [ ] Verify test coverage and CI build status - [ ] Verify documentation (including upgrade notes) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: jira-unsubscr...@kafka.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
