Unified interface for all protocol server implementations. More...

#include <i_protocol_server.h>

Inheritance diagram for kcenon::network::interfaces::i_protocol_server:

Collaboration diagram for kcenon::network::interfaces::i_protocol_server:

Public Types
using	connection_callback_t = std::function<void(std::shared_ptr<i_session>)>
	Callback type for new connections.

using	disconnection_callback_t = std::function<void(std::string_view)>
	Callback type for disconnections (session_id)

using	receive_callback_t = std::function<void(std::string_view, const std::vector<uint8_t>&)>
	Callback type for received data (session_id, data)

using	error_callback_t = std::function<void(std::string_view, std::error_code)>
	Callback type for errors (session_id, error)

Public Member Functions
virtual auto	start (uint16_t port) -> VoidResult=0
	Starts the server and begins listening for connections.

virtual auto	stop () -> VoidResult=0
	Stops the server and closes all connections.

virtual auto	connection_count () const -> size_t=0
	Gets the number of active client connections.

virtual auto	set_connection_callback (connection_callback_t callback) -> void=0
	Sets the callback for new connections.

virtual auto	set_disconnection_callback (disconnection_callback_t callback) -> void=0
	Sets the callback for disconnections.

virtual auto	set_receive_callback (receive_callback_t callback) -> void=0
	Sets the callback for received data.

virtual auto	set_error_callback (error_callback_t callback) -> void=0
	Sets the callback for errors.

Public Member Functions inherited from kcenon::network::interfaces::i_network_component
virtual	~i_network_component ()=default
	Virtual destructor for proper cleanup of derived classes.

	i_network_component (const i_network_component &)=delete

i_network_component &	operator= (const i_network_component &)=delete

	i_network_component (i_network_component &&)=delete

i_network_component &	operator= (i_network_component &&)=delete

Additional Inherited Members
Protected Member Functions inherited from kcenon::network::interfaces::i_network_component
	i_network_component ()=default
	Default constructor (only for derived classes)

virtual auto	is_running () const -> bool=0
	Checks if the component is currently running.

virtual auto	wait_for_stop () -> void=0
	Blocks until the component has stopped.

Detailed Description

Unified interface for all protocol server implementations.

This interface establishes a common contract for all protocol servers (TCP, UDP, HTTP, WebSocket, QUIC, etc.) in the network system. It provides a consistent API for server lifecycle management, connection handling, session management, and data broadcasting across different protocol implementations.

Design Rationale

This interface was created to:

Eliminate code duplication across protocol-specific server implementations
Provide a single, uniform API for all server types
Enable protocol-agnostic facade and adapter patterns
Simplify testing through consistent interface contracts
Support unified session management across all protocols

Protocol Coverage

Implementations include:

TCP servers (messaging_server, secure_messaging_server)
UDP servers (messaging_udp_server, secure_messaging_udp_server)
HTTP servers (http_server)
WebSocket servers (messaging_ws_server)
QUIC servers (messaging_quic_server)

Session Management

All server implementations manage client connections as sessions. Sessions are represented by the i_session interface, which provides:

Unique session identifiers
Per-session data transmission
Session metadata and state

Callback Pattern

Servers use callbacks to notify application code of events:

connection_callback_t: New client connected
disconnection_callback_t: Client disconnected
receive_callback_t: Data received from client
error_callback_t: Error occurred

Thread Safety

All public methods must be thread-safe
Callbacks may be invoked from I/O threads
Session objects are thread-safe

Usage Example

// Create server instance (protocol-specific)
std::shared_ptr<i_protocol_server> server = std::make_shared<messaging_server>();
 
// Set callbacks for events
server->set_connection_callback([](std::shared_ptr<i_session> session) {
    std::cout << "Client connected: " << session->id() << std::endl;
});
 
server->set_receive_callback([](std::string_view session_id, const std::vector<uint8_t>& data) {
    std::cout << "Received " << data.size() << " bytes from " << session_id << std::endl;
});
 
// Start server on port
if (auto result = server->start(8080); !result) {
    // Handle start error
}
 
// Server is now accepting connections...
std::cout << "Active connections: " << server->connection_count() << std::endl;
 
// Stop when done
server->stop();

See also: i_protocol_client; i_session; i_network_component

Definition at line 111 of file i_protocol_server.h.

Member Typedef Documentation

◆ connection_callback_t

using kcenon::network::interfaces::i_protocol_server::connection_callback_t = std::function<void(std::shared_ptr<i_session>)>

Callback type for new connections.

Definition at line 115 of file i_protocol_server.h.

◆ disconnection_callback_t

using kcenon::network::interfaces::i_protocol_server::disconnection_callback_t = std::function<void(std::string_view)>

Callback type for disconnections (session_id)

Definition at line 117 of file i_protocol_server.h.

◆ error_callback_t

using kcenon::network::interfaces::i_protocol_server::error_callback_t = std::function<void(std::string_view, std::error_code)>

Callback type for errors (session_id, error)

Definition at line 121 of file i_protocol_server.h.

◆ receive_callback_t

using kcenon::network::interfaces::i_protocol_server::receive_callback_t = std::function<void(std::string_view, const std::vector<uint8_t>&)>

Callback type for received data (session_id, data)

Definition at line 119 of file i_protocol_server.h.

Member Function Documentation

◆ connection_count()

virtual auto kcenon::network::interfaces::i_protocol_server::connection_count ( ) const -> size_t

nodiscardpure virtual

Gets the number of active client connections.

Returns: The count of currently connected clients.

Definition of "Active"

A connection is considered active if:

Connection is established (handshake complete if applicable)
Session has not been closed
No fatal errors have occurred on the session

Protocol-Specific Notes

TCP/WebSocket/QUIC: Count of established connections
UDP: Count of unique peer endpoints seen recently
HTTP: Count of active persistent connections or requests

Thread Safety

Thread-safe. Uses atomic operations for accurate count.

Performance

O(1) operation. Does not iterate through connections.

Implemented in kcenon::network::internal::adapters::http_server_adapter, kcenon::network::internal::adapters::quic_server_adapter, kcenon::network::internal::adapters::tcp_server_adapter, kcenon::network::internal::adapters::udp_server_adapter, and kcenon::network::internal::adapters::ws_server_adapter.

◆ set_connection_callback()

virtual auto kcenon::network::interfaces::i_protocol_server::set_connection_callback ( connection_callback_t callback ) -> void

pure virtual

Sets the callback for new connections.

Parameters

callback The callback function.

Callback Parameters

session: Shared pointer to the new session object

Callback Behavior

Called when:

TCP: After accept() and initial handshake complete
WebSocket: After HTTP upgrade handshake succeeds
UDP: After first datagram received from new peer
QUIC: After connection establishment handshake
HTTP: After request line and headers parsed (HTTP/1.1)

Session Object

The session object allows:

Sending data to the specific client
Retrieving session metadata (ID, remote endpoint)
Closing the session individually

Thread Safety

The callback may be invoked from I/O threads. If the callback accesses shared state, it must be thread-safe.

Example

server->set_connection_callback([](std::shared_ptr<i_session> session) {
    std::cout << "New client: " << session->id() << std::endl;
    // Send welcome message
    session->send({0x01, 0x02, 0x03});
});

Implemented in kcenon::network::internal::adapters::http_server_adapter, kcenon::network::internal::adapters::quic_server_adapter, kcenon::network::internal::adapters::tcp_server_adapter, kcenon::network::internal::adapters::udp_server_adapter, and kcenon::network::internal::adapters::ws_server_adapter.

◆ set_disconnection_callback()

virtual auto kcenon::network::interfaces::i_protocol_server::set_disconnection_callback ( disconnection_callback_t callback ) -> void

pure virtual

Sets the callback for disconnections.

Parameters

callback The callback function.

Callback Parameters

session_id: String identifier of the disconnected session

Callback Behavior

Called when:

Client closes connection gracefully
Connection lost due to network error
Server closes the session
Timeout or keepalive failure

Clean-up Responsibility

The callback is the appropriate place to:

Remove session from application state
Log disconnection events
Release session-specific resources

Thread Safety

The callback may be invoked from I/O threads. Session cleanup code must be thread-safe.

Example

server->set_disconnection_callback([](std::string_view session_id) {
    std::cout << "Client disconnected: " << session_id << std::endl;
    // Remove from session map
    sessions.erase(std::string(session_id));
});

Implemented in kcenon::network::internal::adapters::http_server_adapter, kcenon::network::internal::adapters::quic_server_adapter, kcenon::network::internal::adapters::tcp_server_adapter, kcenon::network::internal::adapters::udp_server_adapter, and kcenon::network::internal::adapters::ws_server_adapter.

◆ set_error_callback()

virtual auto kcenon::network::interfaces::i_protocol_server::set_error_callback ( error_callback_t callback ) -> void

pure virtual

Sets the callback for errors.

Parameters

callback The callback function.

Callback Parameters

session_id: String identifier of the affected session (may be empty for server-level errors)
error: std::error_code describing the error

Error Categories

Connection errors: Reset, timeout, refused
Protocol errors: Invalid handshake, malformed data
System errors: Out of memory, file descriptor limits
Application errors: Send queue full, rate limit exceeded

Error Handling Strategy

The callback should:

Log the error for diagnostics
Decide whether to close the session
Update error metrics/statistics
Notify monitoring systems if critical

Automatic Disconnection

Some errors trigger automatic session closure:

Connection reset (ECONNRESET)
Protocol violations
Fatal security errors

For these, disconnection_callback will also be invoked.

Thread Safety

The callback may be invoked from I/O threads. Error handling code must be thread-safe.

Example

server->set_error_callback([](std::string_view session_id,
                               std::error_code error) {
    std::cerr << "Error on session " << session_id << ": "
              << error.message() << std::endl;
});

Implemented in kcenon::network::internal::adapters::http_server_adapter, kcenon::network::internal::adapters::quic_server_adapter, kcenon::network::internal::adapters::tcp_server_adapter, kcenon::network::internal::adapters::udp_server_adapter, and kcenon::network::internal::adapters::ws_server_adapter.

◆ set_receive_callback()

virtual auto kcenon::network::interfaces::i_protocol_server::set_receive_callback ( receive_callback_t callback ) -> void

pure virtual

Sets the callback for received data.

Parameters

callback The callback function.

Callback Parameters

session_id: String identifier of the sending session
data: Vector of bytes received

Data Ownership

The data vector is passed by const reference. If the callback needs to retain the data, it must copy it. The data is valid only for the duration of the callback.

Protocol-Specific Notes

TCP: May deliver partial messages (stream-based)
UDP: Delivers complete datagrams (message boundaries preserved)
WebSocket: Delivers complete messages (frame assembled)
QUIC: Delivers complete messages (stream data)

Thread Safety

The callback may be invoked from I/O threads. Multiple callbacks may execute concurrently for different sessions.

Example

server->set_receive_callback([](std::string_view session_id,
                                 const std::vector<uint8_t>& data) {
    std::cout << "Received " << data.size() << " bytes from "
              << session_id << std::endl;
    // Process data...
});

Implemented in kcenon::network::internal::adapters::http_server_adapter, kcenon::network::internal::adapters::quic_server_adapter, kcenon::network::internal::adapters::tcp_server_adapter, kcenon::network::internal::adapters::udp_server_adapter, and kcenon::network::internal::adapters::ws_server_adapter.

◆ start()

virtual auto kcenon::network::interfaces::i_protocol_server::start ( uint16_t port ) -> VoidResult

nodiscardpure virtual

Starts the server and begins listening for connections.

Parameters

port	The port number to listen on.

Returns: VoidResult indicating success or failure.

Behavior

Binds to the specified port on all interfaces (0.0.0.0/::)
Begins accepting incoming connections
Initializes protocol-specific resources
Invokes connection_callback for each new client

Error Conditions

Returns error if already running
Returns error if port is already in use (EADDRINUSE)
Returns error if port binding fails (permission, invalid port)
Returns error if underlying protocol initialization fails

Protocol-Specific Notes

TCP/WebSocket/QUIC: Creates listening socket
UDP: Creates datagram socket, begins receiving
HTTP: May create connection pool or thread pool

Port Range

Valid ports: 1-65535

Privileged ports (< 1024) may require elevated permissions
Port 0 requests OS to assign an available port

Thread Safety

Thread-safe. Only one start operation can succeed at a time. Subsequent calls while running will return an error.

Implemented in kcenon::network::internal::adapters::http_server_adapter, kcenon::network::internal::adapters::quic_server_adapter, kcenon::network::internal::adapters::tcp_server_adapter, kcenon::network::internal::adapters::udp_server_adapter, and kcenon::network::internal::adapters::ws_server_adapter.

◆ stop()

virtual auto kcenon::network::interfaces::i_protocol_server::stop ( ) -> VoidResult

nodiscardpure virtual

Stops the server and closes all connections.

Returns: VoidResult indicating success or failure.

Behavior

Stops accepting new connections
Closes all active client sessions gracefully
Invokes disconnection_callback for each session
Cancels all pending operations
Releases protocol-specific resources

Error Conditions

Returns error if not running

Graceful Shutdown

The stop operation attempts to:

Stop accepting new connections immediately
Close existing connections gracefully (protocol-dependent)
Wait for pending operations to complete (with timeout)
Force-close remaining connections if timeout expires

Protocol-Specific Notes

TCP: Sends FIN to all clients, waits for ACK
WebSocket: Sends close frame to all clients
UDP: Stops receiving, no client "close" needed
QUIC: Sends CONNECTION_CLOSE to all clients

Thread Safety

Thread-safe. Safe to call from any thread including callbacks. The method blocks until shutdown is complete.

Implemented in kcenon::network::internal::adapters::http_server_adapter, kcenon::network::internal::adapters::quic_server_adapter, kcenon::network::internal::adapters::tcp_server_adapter, kcenon::network::internal::adapters::udp_server_adapter, and kcenon::network::internal::adapters::ws_server_adapter.

The documentation for this interface was generated from the following file:

include/kcenon/network/interfaces/i_protocol_server.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Design Rationale

Protocol Coverage

Session Management

Callback Pattern

Thread Safety

Usage Example

Member Typedef Documentation

◆ connection_callback_t

◆ disconnection_callback_t

◆ error_callback_t

◆ receive_callback_t

Member Function Documentation

◆ connection_count()

Definition of "Active"

Protocol-Specific Notes

Thread Safety

Performance

◆ set_connection_callback()

Callback Parameters

Callback Behavior

Session Object

Thread Safety

Example

◆ set_disconnection_callback()

Callback Parameters

Callback Behavior

Clean-up Responsibility

Thread Safety

Example

◆ set_error_callback()

Callback Parameters

Error Categories

Error Handling Strategy

Automatic Disconnection

Thread Safety

Example

◆ set_receive_callback()

Callback Parameters

Data Ownership

Protocol-Specific Notes

Thread Safety

Example

◆ start()

Behavior

Error Conditions

Protocol-Specific Notes

Port Range

Thread Safety

◆ stop()

Behavior

Error Conditions

Graceful Shutdown

Protocol-Specific Notes

Thread Safety