#pragma once

#include <span>
#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.
 */
struct ConnectionHandler {
public:
  virtual ~ConnectionHandler() = default;

  /**
   * Process incoming data from a connection.
   *
   * @param data Incoming data buffer (may be partial message)
   * @param conn Connection reference - server retains ownership
   *
   * 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
   * - Handle partial messages and streaming protocols appropriately
   * - Use conn.get_weak_ref() for async processing if needed
   *
   * @note `data` lifetime ends after the call to on_data_arrived.
   * @note Called from this connection's io thread.
   * @note Handler can safely access connection concurrently via thread-safe
   * methods.
   */
  virtual void on_data_arrived(std::string_view /*data*/, 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 Connection that made write progress - server retains ownership
   * @note Called from this connection's io thread.
   * @note Called during writes, not necessarily when buffer becomes empty
   */
  virtual void on_write_progress(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:
   * - Implementing keep-alive connection reuse
   * - Closing connections after final response
   * - Relieving backpressure conditions
   *
   * @param conn Connection with empty write buffer - server retains ownership
   * @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 &) {}

  /**
   * Called when a new connection is established.
   *
   * @param conn Newly established connection
   *
   * Use this for:
   * - Connection-specific initialization.
   * @note Called from this connection's io 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 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 &) {}

  /**
   * @brief Called after a batch of connections has been processed.
   *
   * 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.
   * 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 *const> /*batch*/) {}
};
