From 8b9b94b76b3aa639d360af910b9c0fa2beb065c2 Mon Sep 17 00:00:00 2001 From: Oluwabusayo Jacobs <68024640+TropicolX@users.noreply.github.com> Date: Sat, 22 Nov 2025 06:22:37 +0100 Subject: [PATCH 1/3] Revise "Include DescribeTopicPartitions in ApiVersions #yk1" Added details for the DescribeTopicPartitions API to the ApiVersions response, including metadata and example response format. --- .../listing-partitions-01-yk1.md | 59 +++++++++++++++---- 1 file changed, 46 insertions(+), 13 deletions(-) diff --git a/stage_descriptions/listing-partitions-01-yk1.md b/stage_descriptions/listing-partitions-01-yk1.md index 33b116f..0f88dbd 100644 --- a/stage_descriptions/listing-partitions-01-yk1.md +++ b/stage_descriptions/listing-partitions-01-yk1.md @@ -1,10 +1,38 @@ -In this stage, you'll add an entry for the `DescribeTopicPartitions` API to the ApiVersions response. +In this stage, you'll add an entry for the `DescribeTopicPartitions` API to the `ApiVersions` response. -🚧 **We're still working on instructions for this stage**. You can find notes on how the tester works below. +### The `ApiVersions` API (Recap) -In the meantime, please use -[this link](https://forum.codecrafters.io/new-topic?category=Challenges&tags=challenge%3Akafka&title=Question+about+yk1%3A+Include+DescribeTopicPartitions+in+ApiVersions&body=%3Cyour+question+here%3E) -to ask questions on the forum. +As a recap, the [`ApiVersions`](https://kafka.apache.org/protocol.html#The_Messages_ApiVersions) API returns the broker's supported API versions. The [response](https://binspec.org/kafka-api-versions-Response-v4) includes a list of APIs, along with their minimum and maximum supported versions. + +In previous stages, you implemented the `ApiVersions` response with a single entry for the `ApiVersions` API itself. Now you'll add a second entry for the `DescribeTopicPartitions` API. + +### The `DescribeTopicPartitions` API + +The [`DescribeTopicPartitions`](https://kafka.apache.org/protocol.html#The_Messages_DescribeTopicPartitions) API returns metadata about [topics](https://kafka.apache.org/documentation/#intro_concepts_and_terms) and their [partitions](https://kafka.apache.org/documentation/#:~:text=partitioned). For this stage, you only need to advertise support for it in the `ApiVersions` response. You'll implement the actual API handling in later stages. + +Your `ApiVersions` response should now include two entries in the `api_keys` array: + +- `ApiVersions` (API key `18`): `min_version` `0`, `max_version` `4`. +- `DescribeTopicPartitions` (API key `75`): `min_version` `0`, `max_version` `0`. + +Here's an example of what your updated response might look like: + +```bash +00 00 00 1d // message_size: 29 bytes +ab cd ef 12 // correlation_id: (matches request) +00 00 // error_code: 0 (no error) +03 // api_keys array: 2 elements (compact array encoding) +00 12 // api_key: 18 (ApiVersions) +00 00 // min_version: 0 +00 04 // max_version: 4 +00 // TAG_BUFFER: empty +00 4b // api_key: 75 (DescribeTopicPartitions) +00 00 // min_version: 0 +00 00 // max_version: 0 +00 // TAG_BUFFER: empty +00 00 00 00 // throttle_time_ms: 0 +00 // TAG_BUFFER: empty +``` ### Tests @@ -14,19 +42,24 @@ The tester will execute your program like this: $ ./your_program.sh /tmp/server.properties ``` -It'll then connect to your server on port 9092 and send a valid `ApiVersions` (v4) request. +It will then connect to your server on port `9092` and send a valid `ApiVersions` (v4) request: + +``` +$ echo -n "0000001a0012000467890abc00096b61666b612d636c69000a6b61666b612d636c6904302e3100" | xxd -r -p | nc localhost 9092 | hexdump -C +``` The tester will validate that: -- The first 4 bytes of your response (the "message length") are valid. +- The `message_size` field correctly represents the size of the header and body. - The correlation ID in the response header matches the correlation ID in the request header. -- The error code in the response body is `0` (No Error). -- The response body contains at least one entry for the API key 18 (`ApiVersions`) and one entry for the API key 75 (`DescribeTopicPartitions`). -- The response for the API key 18 (`ApiVersions`) has a `MaxVersion` of at least 4, and a `MinVersion` of at least 0. -- The response for the API key 75 (`DescribeTopicPartitions`) has a `MaxVersion` of at least 0, and a `MinVersion` of at least 0. +- The `error_code` in the response body is `0` (No Error). +- The response body includes entries for both API key 18 (`ApiVersions`) and API key 75 (`DescribeTopicPartitions`). +- The API key `18` (`ApiVersions`) response has a `min_version` of `0` and a `max_version` of at least `4` +- The response for the API key `75` (`DescribeTopicPartitions`) has a `MaxVersion` of at least `0`, and a `MinVersion` of at least `0`. +- The API key `75` (`DescribeTopicPartitions`) response has a `min_version` of `0` and a `max_version` of at least `0`. ### Notes -- The `MaxVersion` for the `DescribeTopicPartitions` and `ApiVersions` are different. For `ApiVersions`, it is 4. For `DescribeTopicPartitions`, it is 0. +- The `MaxVersion` for the `DescribeTopicPartitions` and `ApiVersions` is different. For `ApiVersions`, it is 4. For `DescribeTopicPartitions`, it is 0. - You'll still need to include the entry for `ApiVersions` in your response to pass previous stages. -- We'll get to implementing the `DescribeTopicPartitions` request in later stages, in this stage you only need to add an entry to the ApiVersions response. +- We'll get to implementing the `DescribeTopicPartitions` request in later stages. For this stage, you only need to add an entry to the ApiVersions response. From ea8083f6a3479f76be7044aef81d5515dfbcbd2c Mon Sep 17 00:00:00 2001 From: Oluwabusayo Jacobs <68024640+TropicolX@users.noreply.github.com> Date: Sun, 23 Nov 2025 17:35:14 +0100 Subject: [PATCH 2/3] Fix formatting and clarify API key version details --- stage_descriptions/listing-partitions-01-yk1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stage_descriptions/listing-partitions-01-yk1.md b/stage_descriptions/listing-partitions-01-yk1.md index 0f88dbd..29f92c5 100644 --- a/stage_descriptions/listing-partitions-01-yk1.md +++ b/stage_descriptions/listing-partitions-01-yk1.md @@ -54,12 +54,12 @@ The tester will validate that: - The correlation ID in the response header matches the correlation ID in the request header. - The `error_code` in the response body is `0` (No Error). - The response body includes entries for both API key 18 (`ApiVersions`) and API key 75 (`DescribeTopicPartitions`). -- The API key `18` (`ApiVersions`) response has a `min_version` of `0` and a `max_version` of at least `4` +- The API key `18` (`ApiVersions`) response has a `min_version` of `0` and a `max_version` of at least `4`. - The response for the API key `75` (`DescribeTopicPartitions`) has a `MaxVersion` of at least `0`, and a `MinVersion` of at least `0`. - The API key `75` (`DescribeTopicPartitions`) response has a `min_version` of `0` and a `max_version` of at least `0`. ### Notes - The `MaxVersion` for the `DescribeTopicPartitions` and `ApiVersions` is different. For `ApiVersions`, it is 4. For `DescribeTopicPartitions`, it is 0. -- You'll still need to include the entry for `ApiVersions` in your response to pass previous stages. +- You'll still need to include the entry for `ApiVersions` in your response to pass the previous stages. - We'll get to implementing the `DescribeTopicPartitions` request in later stages. For this stage, you only need to add an entry to the ApiVersions response. From c8937554fea32b006110f0ffb7b4b146bcee83eb Mon Sep 17 00:00:00 2001 From: Oluwabusayo Jacobs <68024640+TropicolX@users.noreply.github.com> Date: Sun, 23 Nov 2025 17:40:02 +0100 Subject: [PATCH 3/3] Update listing-partitions-01-yk1.md --- stage_descriptions/listing-partitions-01-yk1.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/stage_descriptions/listing-partitions-01-yk1.md b/stage_descriptions/listing-partitions-01-yk1.md index 29f92c5..a730179 100644 --- a/stage_descriptions/listing-partitions-01-yk1.md +++ b/stage_descriptions/listing-partitions-01-yk1.md @@ -55,11 +55,9 @@ The tester will validate that: - The `error_code` in the response body is `0` (No Error). - The response body includes entries for both API key 18 (`ApiVersions`) and API key 75 (`DescribeTopicPartitions`). - The API key `18` (`ApiVersions`) response has a `min_version` of `0` and a `max_version` of at least `4`. -- The response for the API key `75` (`DescribeTopicPartitions`) has a `MaxVersion` of at least `0`, and a `MinVersion` of at least `0`. - The API key `75` (`DescribeTopicPartitions`) response has a `min_version` of `0` and a `max_version` of at least `0`. ### Notes -- The `MaxVersion` for the `DescribeTopicPartitions` and `ApiVersions` is different. For `ApiVersions`, it is 4. For `DescribeTopicPartitions`, it is 0. - You'll still need to include the entry for `ApiVersions` in your response to pass the previous stages. - We'll get to implementing the `DescribeTopicPartitions` request in later stages. For this stage, you only need to add an entry to the ApiVersions response.