Merge pull request #75 from codecrafters-io/TropicolX-patch-2

Revise "Send Correlation ID #nv3" (stage 2)

Author: TropicolX

stage_descriptions/base-02-nv3.md

@@ -1,8 +1,8 @@
 In this stage, you'll send a response with a correlation ID.
 
-### Response message
+### The Kafka Wire Protocol
 
-Kafka brokers communicate with clients through the [Kafka wire protocol](https://kafka.apache.org/protocol.html). The protocol uses a request-response model, where the client sends a request message and the broker replies with a response message.
+Kafka brokers communicate with clients through the [Kafka wire protocol](https://kafka.apache.org/protocol.html). The protocol uses a request-response model: the client sends a request message, and the broker replies with a response message.
 
 A Kafka response message has three parts:
 1. `message_size`
@@ -11,26 +11,32 @@ A Kafka response message has three parts:
 
 For this stage, you can ignore the body and just focus on `message_size` and the header. You'll learn about response bodies in a later stage.
 
-#### The `message_size` field
+### The `message_size` Field
 
-The [`message_size`](https://kafka.apache.org/protocol.html#protocol_common) field is a 32-bit signed integer. It specifies the size of the header and body.
+The [`message_size`](https://kafka.apache.org/protocol.html#protocol_common) field is a 32-bit signed integer that specifies the size of the header and body in bytes.
 
-For this stage, the tester will only assert that your `message_size` field is 4 bytes long—it won't check the value. You'll implement correct `message_size` values in a later stage.
+All integers in the Kafka protocol are in [big-endian](https://developer.mozilla.org/en-US/docs/Glossary/Endianness) byte order. For example, a `message_size` of `2` looks like this:
 
-#### Header
+```
+00 00 00 02  // message_size: 2
+```
+
+For this stage, you only need to ensure that your `message_size` field is 4 bytes long. You'll implement the correct `message_size` values in a later stage.
 
-Kafka has a few different header versions. The way Kafka determines which header version to use is a bit complicated and is outside the scope of this challenge. For more information, take a look at [KIP-482](https://cwiki.apache.org/confluence/display/KAFKA/KIP-482%3A+The+Kafka+Protocol+should+Support+Optional+Tagged+Fields) and this [Stack Overflow answer](https://stackoverflow.com/a/71853003).
+### Response Header v0
 
-In this stage, you will use [response header v0](https://kafka.apache.org/protocol.html#protocol_messages) (scroll down).
+Kafka has multiple header versions. In this stage, you will use [response header v0](https://kafka.apache.org/protocol.html#protocol_messages), which is the simplest version. 
 
-Response header v0 contains a single field: [`correlation_id`](https://developer.confluent.io/patterns/event/correlation-identifier/). This field lets clients match responses to their original requests. Here's how it works:
+Response header v0 contains a single field: [`correlation_id`](https://developer.confluent.io/patterns/event/correlation-identifier/). This field lets clients match responses to their original requests.
 
-1. The client generates a correlation ID.
-2. The client sends a request that includes the correlation ID.
-3. The broker sends a response that includes the same correlation ID.
-4. The client receives the response and matches the correlation ID to the original request.
+The `correlation_id` field is also a 32-bit signed integer. For this stage, your program must respond with a hard-coded `correlation_id` of `7`.
 
-The `correlation_id` field is a 32-bit signed integer. For this stage, your program must respond with a hard-coded `correlation_id` of 7.
+Putting it all together, your complete response should be 8 bytes long: 4 bytes for `message_size` and 4 bytes for the header (`correlation_id`).
+
+```
+00 00 00 00  // message_size:   0 (any value works for this stage)
+00 00 00 07  // correlation_id: 7
+```
 
 ### Tests
 
@@ -39,18 +45,22 @@ The tester will execute your program like this:
 $ ./your_program.sh
 ```
 
-It'll then connect to your broker on port 9092 and send a request:
+It will then connect to your broker on port `9092` and send a request:
 ```
 $ echo -n "Placeholder request" | nc -v localhost 9092 | hexdump -C
 ```
 
-Your broker must send a response with a correlation ID of 7:
-```java
-00 00 00 00  // message_size:   0 (any value works)
+Your broker must send a response with this structure:
+```
+00 00 00 00  // message_size:   0 (any value works for this stage)
 00 00 00 07  // correlation_id: 7
 ```
 
+The tester will verify that:
+- Your response is 8 bytes total (4 for `message_size`, 4 for `correlation_id`).
+- The `correlation_id` field contains the value `7`.
+
 ### Notes
 
 - For this stage, you don't need to parse the request. You'll learn about request parsing in a later stage.
-- All integers are in [big-endian](https://developer.mozilla.org/en-US/docs/Glossary/Endianness) order.
+- All integers are in [big-endian](https://developer.mozilla.org/en-US/docs/Glossary/Endianness) order.