122 lines
4.3 KiB
C++
122 lines
4.3 KiB
C++
#pragma once
|
|
|
|
#include <span>
|
|
#include <string_view>
|
|
|
|
// Forward declarations to avoid circular dependency
|
|
struct Connection;
|
|
|
|
// Include Arena header since PendingResponse uses Arena by value
|
|
#include "arena.hpp"
|
|
|
|
/**
|
|
* Represents a response queued by pipeline threads for protocol processing.
|
|
* Contains JSON response data that can be wrapped by any protocol.
|
|
*/
|
|
struct PendingResponse {
|
|
void *protocol_context; // Arena-allocated protocol-specific context
|
|
std::string_view response_json; // JSON response body (arena-allocated)
|
|
Arena arena; // Arena containing response data and context
|
|
};
|
|
|
|
/**
|
|
* 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
|
|
* TODO Add bytes written argument?
|
|
*/
|
|
virtual void on_write_progress(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 or on_write_progress 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*/) {}
|
|
|
|
/**
|
|
* Called before processing outgoing writes on a connection.
|
|
*
|
|
* This hook allows protocol handlers to process queued responses
|
|
* before actual socket writes occur. Used for response ordering,
|
|
* serialization, and other preprocessing.
|
|
*
|
|
* @param conn Connection about to write data
|
|
* @param pending_responses Responses queued by pipeline threads
|
|
* @note Called from this connection's io thread.
|
|
* @note Called when EPOLLOUT event occurs
|
|
*/
|
|
virtual void
|
|
on_preprocess_writes(Connection &conn,
|
|
std::span<PendingResponse> pending_responses) {}
|
|
};
|