#pragma once

#include <memory>
#include <string_view>

// Forward declaration to avoid circular dependency
struct Connection;

/**
 * Abstract interface for handling connection data processing.
 *
 * This interface decouples protocol-specific logic (HTTP, WebSocket, etc.)
 * from the underlying networking infrastructure. Implementations handle
 * parsing incoming data and generating appropriate responses.
 *
 * The networking layer manages connection lifecycle, I/O multiplexing,
 * and efficient data transfer, while handlers focus purely on protocol logic.
 */
class ConnectionHandler {
public:
  virtual ~ConnectionHandler() = default;

  /**
   * Process incoming data from a connection.
   *
   * @param data Incoming data buffer (may be partial message)
   * @param conn_ptr Unique pointer to connection - handler can take ownership
   * by releasing it
   *
   * Implementation should:
   * - Parse incoming data using arena allocator when needed
   * - Use conn_ptr->appendMessage() to queue response data to be sent
   * - Handle partial messages and streaming protocols appropriately
   * - Can take ownership by calling conn_ptr.release() to pass to other threads
   * - If ownership is taken, handler must call Server::releaseBackToServer()
   * when done
   * @note `data` is *not* owned by the connection arena, and its lifetime ends
   * after the call to process_data.
   * @note May be called from an arbitrary network thread.
   */
  virtual void process_data(std::string_view data,
                            std::unique_ptr<Connection> &conn_ptr) = 0;

  /**
   * Called when a new connection is established.
   *
   * @param conn Newly established connection
   *
   * Use this for:
   * - Connection-specific initialization.
   * @note May be called from an arbitrary accept thread.
   */
  virtual void on_connection_established(Connection &) {}

  /**
   * Called when a connection is about to be closed.
   *
   * @param conn Connection being closed
   *
   * Use this for:
   * - Cleanup of connection-specific resources.
   * @note May be called from an arbitrary accept thread.
   */
  virtual void on_connection_closed(Connection &) {}
};