Rename append_message to send_response and update Connection construction docs

design.md

@@ -264,7 +264,7 @@ CommitRequest {
 
 1. **Request Processing**: Handler creates request-scoped arena for parsing request data
 1. **Response Generation**: Handler uses same arena for response construction (headers, JSON, etc.)
-1. **Response Queuing**: Handler calls `conn->append_message()` passing span + arena ownership
+1. **Response Queuing**: Handler calls `conn->send_response()` passing span + arena ownership
 1. **Response Writing**: I/O thread writes messages to socket, arena freed after completion
 
 > **Note**: Call `conn->reset()` periodically to reclaim arena memory. Best practice is after all outgoing bytes have been written.
@@ -411,7 +411,7 @@ public:
     Arena& arena = conn.get_arena();
 
     // Generate response
-    conn.append_message("HTTP/1.1 200 OK\r\n\r\nHello World");
+    conn.send_response("HTTP/1.1 200 OK\r\n\r\nHello World");
 
     // Server retains ownership
   }
@@ -430,7 +430,7 @@ public:
     work_queue.push([weak_conn, data = std::string(data)]() {
       // Process asynchronously - connection may be closed
       if (auto conn_ref = weak_conn.lock()) {
-        conn_ref->append_message("Async response");
+        conn_ref->send_response("Async response");
       }
     });
   }
@@ -483,7 +483,7 @@ class YesHandler : ConnectionHandler {
 public:
   void on_connection_established(Connection &conn) override {
     // Write an initial "y\n"
-    conn.append_message("y\n");
+    conn.send_response("y\n");
   }
 
   void on_write_progress(Connection &conn) override {
@@ -491,7 +491,7 @@ public:
       // Don't use an unbounded amount of memory
       conn.reset();
       // Write "y\n" repeatedly
-      conn.append_message("y\n");
+      conn.send_response("y\n");
     }
   }
 };
@@ -519,7 +519,7 @@ auto weak_conn = conn.get_weak_ref();
 background_processor.submit([weak_conn]() {
   // Do work...
   if (auto conn_ref = weak_conn.lock()) {
-    conn_ref->append_message("Background result");
+    conn_ref->send_response("Background result");
   }
   // Connection automatically cleaned up by server
 });

src/connection.hpp

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <atomic>
 #include <cassert>
 #include <cstring>
 #include <deque>
@@ -32,7 +33,7 @@ enum class ConnectionShutdown {
 /**
  * Base interface for sending messages to a connection.
  * This restricted interface is safe for use by pipeline threads,
- * containing only the append_message method needed for responses.
+ * containing only the send_response method needed for responses.
  * Pipeline threads should use WeakRef<MessageSender> to safely
  * send responses without accessing other connection functionality
  * that should only be used by the I/O thread.
@@ -76,9 +77,9 @@ struct MessageSender {
  *
  * Threading model:
  * - Single mutex protects state shared with pipeline threads
- * - Pipeline threads call Connection methods (append_message, etc.)
+ * - Pipeline threads call Connection methods (send_response, etc.)
  * - I/O thread processes socket events and message queue
- * - Pipeline threads register epoll write interest via append_message
+ * - Pipeline threads register epoll write interest via send_response
  * - Connection tracks closed state to prevent EBADF errors
  *
  * Arena allocator usage:
@@ -165,7 +166,7 @@ struct Connection : MessageSender {
    *   if (auto conn = weak_conn.lock()) {
    *     Arena arena;
    *     auto response = process_request(request_data, arena);
-   *     conn->append_message({&response, 1}, std::move(arena));
+   *     conn->send_response(response_context, response_json, std::move(arena));
    *   }
    * });
    * ```
@@ -261,8 +262,9 @@ private:
    *
    * Creates a new connection with the specified network address, file
    * descriptor, and associated handler. Automatically increments the global
-   * active connection counter and calls the handler's
+   * active connection counter. The caller (Server) is responsible for
-   * on_connection_established() method.
+   * initializing the self weak reference and invoking
+   * on_connection_established().
    *
    * @param addr Network address of the remote client (IPv4/IPv6 compatible)
    * @param fd File descriptor for the socket connection

src/connection_handler.hpp

@@ -42,7 +42,7 @@ public:
    * Implementation should:
    * - Create request-scoped Arena for parsing and response generation
    * - Parse incoming data using the request arena
-   * - Use conn.append_message() to queue response data to be sent
+   * - Use conn.send_response() to queue response data to be sent
    * - Handle partial messages and streaming protocols appropriately
    * - Use conn.get_weak_ref() for async processing if needed
    *

tools/check_snake_case.py

@@ -78,7 +78,7 @@ def check_snake_case_violations(filepath, check_new_only=True):
         # Common HTTP parser callback names (external API)
         r"\b(onUrl|onHeaderField|onHeaderFieldComplete|onHeaderValue|onHeaderValueComplete|onHeadersComplete|onBody|onMessageComplete)\b",
         # Known legacy APIs we can't easily change
-        r"\b(user_data|get_arena|append_message)\b",
+        r"\b(user_data|get_arena|send_response)\b",
     ]
 
     try: