The `Topic` and Partitioning Logic

Diagram

Topic

The abstraction of a named stream of records and its relationship to the broker's metadata. A Topic represents a logical grouping of partitions, and its structure is determined by the broker's current state. In the Kotlin client, a TopicHandle is obtained from a Producer and contains the TopicName and a list of available PartitionIds (Publishing.kt:19-22).

PartitionFor

The mechanics of mapping a record key to a specific PartitionId using round-robin or hashing. The selection logic depends on whether a key is provided:

• Unkeyed records: Uses a round-robin strategy where a counter is incremented to ensure an even spread across partitions (Publishing.kt:40-42).
• Keyed records: Uses a Partitioner (defaulting to Fnv1a) to map the key to a partition (booblik-client/src/main/kotlin/ru/workinprogress/booblik/net/client/Publishing.kt:23, 44).

Metadata

The protocol for discovering existing topics and the error behavior when requesting unknown topics. The client can request metadata for all topics or a specific subset (BooblikClient.kt:70). If a requested topic does not exist on the broker, the request fails with an UNKNOWN_TOPIC_OR_PARTITION error rather than simply omitting the topic from the response (BooblikServer.kt:75-77).

PartitionRegistry

The server-side management of topic-partition mappings and the ordering of responses. The PartitionRegistry holds a map of Key (topic and partition) to PartitionHandle (BooblikServer.kt:79-81). When describing all partitions, the registry ensures the output is ordered by topic name and then by partition ID to ensure deterministic response ordering (BooblikServer.kt:94-97).

MetadataTest

Verification of topic existence, partition counts, and the distinction between empty and non-existent topics. The tests verify that:

• An empty metadata request describes every topic the broker has (MetadataTest.kt:30-37).
• Naming specific topics narrows the response to only those topics (MetadataTest.kt:50-55).
• An unknown topic results in an error rather than an empty list, preventing ambiguity between a non-existent topic and an empty one (MetadataTest.kt:58-63).

Key files

Behaviour that surprise

• Round-robin vs Random: In TopicHandle.partitionFor, round-robin is used instead of random for unkeyed records because random distribution can visibly clump at small counts, which might be mistaken for a bug (Publishing.kt:31-33).
• Error vs Omission: Requesting a non-existent topic via metadata returns an error code rather than an empty list to distinguish "no such topic" from "topic exists but is empty" (BooblikServer.kt:75-77).
• Deterministic Ordering: The PartitionRegistry.describe function explicitly sorts entries by topic and partition to ensure that identical requests result in identical response byte sequences (BooblikServer.kt:94-97).