Metadata Retrieval

Generated page

Model gemma-mtp, commit ef58254ca7be, 2026-08-16, sources: 6. Edit the code or the hand-written documentation instead.

A MetadataRequest is a specialized request that does not target a specific partition but rather asks the broker for information about one or more topics Session.kt:94-97. If the request contains no topics, the broker is expected to return metadata for all available topics Session.kt:124-126.

TopicMetadata and PartitionMetadata

The broker responds with a hierarchy of metadata structures. A TopicMetadata object contains a list of PartitionMetadata for each partition in a topic Session.kt:136-149.

The PartitionMetadata includes:

Field	Description
`id`	The partition identifier
`logStartOffset`	The first offset currently available in the log after retention `Session.kt:142`
`highWatermark`	The first offset that does not exist yet (the next expected offset) `Session.kt:146`

UNKNOWN_TOPIC_OR_PARTITION Error Handling

The protocol enforces strict topic validation. If a request names a topic that the broker does not possess, the broker must fail the entire request with UNKNOWN_TOPIC_OR_PARTITION rather than simply omitting the missing topic from the response Session.kt:115-118. This distinction ensures that a client can differentiate between a topic that is empty and a topic that does not exist Session.kt:127-131.

MetadataResponse Decoding

The decoding process involves parsing a series of nested structures from the wire format wire.py:209-232. The sequence is as follows:

Topic Count: An integer representing the number of topics wire.py:211.
Topic Name: A length-prefixed UTF-8 string wire.py:216-219.
Partition Count: An integer representing the number of partitions in the topic wire.py:221.
Partition Data: A sequence of PartitionInfo containing the partition ID, log start offset, and high watermark wire.py:226.

Metadata Conformance Testing

The conformance harness verifies that the client correctly interprets the broker's response by checking the reported offsets Program.cs:107. Specifically, it validates that the partition ID, logStartOffset, and highWatermark are correctly extracted and printed to the standard output Program.cs:107.

Key files

File	Lines	What is there
`…/net/Session.kt`	`121-152`	The logic for handling and responding to `MetadataRequest`
`…/booblik/wire.py`	`209-232`	The Python implementation of metadata response decoding
`…/harness/wire.py`	`109-132`	The reference implementation of metadata request encoding and decoding

Behaviour that surprises

The highWatermark reported in PartitionMetadata is read directly from the log's nextOffset rather than a published watermark to ensure it reflects what is actually readable Session.kt:144-146.
In MetadataRequest, if a request names no topics, the broker returns metadata for everything Session.kt:124-125.
A MetadataResponse that is cut short by a broker restart is treated as a ProtocolError rather than a successful empty response wire.py:230-232.