113 lines
4.0 KiB
C++
113 lines
4.0 KiB
C++
#pragma once
|
|
|
|
#include <memory>
|
|
#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_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 on_data_arrived.
|
|
* @note May be called from an arbitrary server thread.
|
|
*/
|
|
virtual void on_data_arrived(std::string_view /*data*/,
|
|
std::unique_ptr<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.
|
|
*
|
|
* @param conn Newly established connection
|
|
*
|
|
* Use this for:
|
|
* - Connection-specific initialization.
|
|
* @note May be called from an arbitrary server 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 server thread.
|
|
*/
|
|
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.
|
|
* 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.
|
|
*/
|
|
virtual void
|
|
on_batch_complete(std::span<std::unique_ptr<Connection>> /*batch*/) {}
|
|
};
|