Separate Connection and Request lifetimes

src/connection_handler.hpp

@@ -3,8 +3,6 @@
 #include <span>
 #include <string_view>
 
-#include "reference.hpp"
-
 // Forward declaration to avoid circular dependency
 struct Connection;
 
@@ -36,7 +34,7 @@ public:
    * - Use conn.get_weak_ref() for async processing if needed
    *
    * @note `data` lifetime ends after the call to on_data_arrived.
-   * @note May be called from an arbitrary server thread.
+   * @note Called from this connection's io thread.
    * @note Handler can safely access connection concurrently via thread-safe
    * methods.
    */
@@ -51,7 +49,7 @@ public:
    * - Progress monitoring for long-running transfers
    *
    * @param conn Connection that made write progress - server retains ownership
-   * @note May be called from an arbitrary server thread.
+   * @note Called from this connection's io thread.
    * @note Called during writes, not necessarily when buffer becomes empty
    */
   virtual void on_write_progress(Connection &) {}
@@ -66,7 +64,7 @@ public:
    * - Relieving backpressure conditions
    *
    * @param conn Connection with empty write buffer - server retains ownership
-   * @note May be called from an arbitrary server thread.
+   * @note Called from this connection's io thread.
    * @note Only called on transitions from non-empty → empty buffer
    */
   virtual void on_write_buffer_drained(Connection &) {}
@@ -78,7 +76,7 @@ public:
    *
    * Use this for:
    * - Connection-specific initialization.
-   * @note May be called from an arbitrary server thread.
+   * @note Called from this connection's io thread.
    */
   virtual void on_connection_established(Connection &) {}
 
@@ -89,7 +87,8 @@ public:
    *
    * Use this for:
    * - Cleanup of connection-specific resources.
-   * @note May be called from an arbitrary server thread.
+   * @note Called from this connection's io thread, or possibly a foreign thread
+   * that has locked the MessageSender associated with this connection.
    */
   virtual void on_connection_closed(Connection &) {}
 
@@ -101,6 +100,7 @@ public:
    * All connections remain server-owned.
    *
    * @param batch A span of connection references in the batch.
+   * @note Called from this connection's io thread.
    */
-  virtual void on_batch_complete(std::span<Connection *> /*batch*/) {}
+  virtual void on_batch_complete(std::span<Connection *const> /*batch*/) {}
 };