Add explanatory comments

tests/test_http_handler.cpp

@@ -10,6 +10,20 @@
 #include <thread>
 #include <unistd.h>
 
+// Test to demonstrate HTTP pipelining response ordering issue
+//
+// HTTP/1.1 pipelining allows multiple requests to be sent on a single
+// connection without waiting for responses, but responses MUST be sent in the
+// same order as requests were received (RFC 2616 Section 8.1.2.2).
+//
+// This test sends two pipelined requests:
+// 1. GET /ok - Slow response (goes through 4-stage pipeline processing)
+// 2. GET /metrics - Fast response (handled directly, just collects metrics)
+//
+// Even though /ok takes longer to process due to pipeline overhead, the /ok
+// response should be sent first since it was requested first. Currently this
+// test FAILS because the faster /metrics response completes before /ok and
+// gets sent out of order.
 TEST_CASE("HTTP pipelined responses out of order") {
   weaseldb::Config config;
   HttpHandler handler(config);
@@ -18,7 +32,10 @@ TEST_CASE("HTTP pipelined responses out of order") {
 
   auto runThread = std::thread{[&]() { server->run(); }};
 
-  // Send /ok and /metrics in one write call
+  // Send two pipelined requests in a single write() call
+  // Request order: /ok first, then /metrics
+  // Expected response order: /ok response first, then /metrics response
+  // Actual result: /metrics response first (fast), then /ok response (slow)
   std::string pipelined_requests = "GET /ok HTTP/1.1\r\n"
                                    "Host: localhost\r\n"
                                    "Connection: keep-alive\r\n"
@@ -88,7 +105,8 @@ TEST_CASE("HTTP pipelined responses out of order") {
   std::size_t ok_pos = response_data.find(ok_response_header);
   REQUIRE(ok_pos != std::string::npos);
 
-  // Count HTTP response status lines before the ok_response_header
+  // Count HTTP response status lines before the /ok response body
+  // This tests response ordering: should be exactly 1 (the /ok response itself)
   std::string before_ok = response_data.substr(0, ok_pos);
   int http_response_count = 0;
   std::size_t pos = 0;
@@ -97,8 +115,10 @@ TEST_CASE("HTTP pipelined responses out of order") {
     pos += 8;
   }
 
-  // Assert there's exactly one HTTP response line before ok_response_header
+  // Assert there's exactly one HTTP response line before /ok response body
-  // This would fail if /metrics response comes before /ok response
+  // If http_response_count == 2, it means /metrics response came first (wrong
+  // order) If http_response_count == 1, it means /ok response came first
+  // (correct order)
   CHECK(http_response_count == 1);
 
   close(fd);