Add on_write_buffer_drained

src/connection_handler.hpp

@@ -43,11 +43,37 @@ public:
                                std::unique_ptr<Connection> &) {};
 
   /**
-   * Successfully wrote data on the connection.
+   * Called when data has been successfully written to the connection.
+   *
+   * This is called during write operations to indicate progress, useful for:
+   * - Streaming large responses (files, data feeds, etc.)
+   * - Implementing backpressure for continuous data streams
+   * - Progress monitoring for long-running transfers
+   *
+   * @param conn_ptr Connection that made write progress - handler can take
+   * ownership
    * @note May be called from an arbitrary server thread.
+   * @note Called during writes, not necessarily when buffer becomes empty
    */
   virtual void on_write_progress(std::unique_ptr<Connection> &) {}
 
+  /**
+   * Called when the connection's outgoing write buffer becomes empty.
+   *
+   * This indicates all queued messages have been successfully written
+   * to the socket. Useful for:
+   * - Resetting arena allocators safely
+   * - Implementing keep-alive connection reuse
+   * - Closing connections after final response
+   * - Relieving backpressure conditions
+   *
+   * @param conn_ptr Connection with empty write buffer - handler can take
+   * ownership
+   * @note May be called from an arbitrary server thread.
+   * @note Only called on transitions from non-empty → empty buffer
+   */
+  virtual void on_write_buffer_drained(std::unique_ptr<Connection> &) {}
+
   /**
    * Called when a new connection is established.
    *
@@ -73,10 +99,11 @@ public:
   /**
    * @brief Called after a batch of connections has been processed.
    *
-   * This hook is called after on_data_arrived or on_write_progress has been
-   * called for each connection in the batch. The handler can take ownership of
-   * the connections by moving the unique_ptr out of the span. Any connections
-   * left in the span will remain owned by the server.
+   * This hook is called after on_data_arrived, on_write_progress, or
+   * on_write_buffer_drained has been called for each connection in the batch.
+   * The handler can take ownership of the connections by moving the unique_ptr
+   * out of the span. Any connections left in the span will remain owned by the
+   * server.
    *
    * @param batch A span of unique_ptrs to the connections in the batch.
    */