liuliuOD commented on code in PR #23692:
URL: https://github.com/apache/kafka/pull/23692#discussion_r4176990594
##########
docs/design/protocol.md:
##########
@@ -138,7 +138,9 @@ The protocol is built out of the following primitive types.
{{< include-html file="/static/{version}/generated/protocol_types.html" >}}
-Message versions marked as flexible use the compact encoding for
variable-length fields. In particular, arrays use `COMPACT_ARRAY` rather than
`ARRAY`; strings and byte arrays similarly use their corresponding `COMPACT_*`
types. Compact encodings store their length as an unsigned variable-length
integer instead of a fixed-width integer. Flexible versions also include a
tagged-fields section at the end of every request and response component.
+By default, message versions marked as flexible use the compact encoding for
variable-length fields. In particular, arrays use `COMPACT_ARRAY` rather than
`ARRAY`; strings and byte arrays similarly use their corresponding `COMPACT_*`
types. Compact encodings store their length as an unsigned variable-length
integer instead of a fixed-width integer.
+
+Individual fields can override this encoding in the message schema. For
example, `ClientId` in flexible request headers uses `NULLABLE_STRING` with a
two-byte length prefix, rather than `COMPACT_NULLABLE_STRING`, so that older
brokers can read the header of an `ApiVersions` request. Flexible versions also
include a tagged-fields section at the end of every request and response
component.
Review Comment:
Agreed. The tagged-fields sentence describes flexible versions in general,
so it belongs in the first paragraph. The new paragraph should focus on
field-level encoding exceptions such as ClientId.
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
