StormByte-Network 4.0.0
C++26 networking module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Network::Server Class Referenceabstract

Abstract application server. More...

#include <StormByte/network/server.hxx>

Inheritance diagram for StormByte::Network::Server:
Collaboration diagram for StormByte::Network::Server:

Public Member Functions

 Server (DeserializePacketFunction deserialize_packet_function, StormByte::Safe::Shared< Logger::Log > logger)
 Construct with a packet factory and a logger.
 Server (const Server &other)=delete
 Copy constructor (deleted).
 Server (Server &&other) noexcept
 Stop the source before transferring its inactive state.
virtual ~Server () noexcept
 Destructor (joins threads, disconnects clients).
Server & operator= (const Server &other)=delete
 Copy assignment (deleted).
Server & operator= (Server &&other) noexcept
 Stop both servers before transferring inactive state.
bool Connect (const Connection::Protocol &protocol, std::string_view address, const unsigned short &port) override
 Bind, listen and start the accept thread.
bool ConfigureTLS (const Crypto::TLS::ServerConfiguration &configuration, bool refresh_validation_time=true) noexcept
 Require TLS for new application and remote-file connections.
bool DisableTLS () noexcept
 Restore plaintext while the server is stopped.
void Disconnect () noexcept override
 Stop accept, disconnect clients and close the listener.
Connection::Status Status () const noexcept override
 Listener / server status.
StormByte::Safe::Shared< ServerTelemetry > Telemetry () const noexcept
 Shared live telemetry aggregated across this Server's sessions.
bool Announce (const Connection::Protocol &protocol, unsigned short discovery_port) noexcept
 Start listening for discovery queries on discovery_port.
void StopAnnounce () noexcept
 Stop the discovery listener.

Protected Member Functions

virtual bool AllowIncomingOpcode (std::string_view uuid, Transport::Packet::OpcodeType opcode) const noexcept
 Admit an application opcode before its pipeline and factory run.
virtual bool AllowOutgoingOpcode (std::string_view uuid, Transport::Packet::OpcodeType opcode) const noexcept
 Admit a response opcode before output transformation.
RemoteFileMount MountRemoteFileReader (std::string_view client_uuid, std::string_view path, std::uint16_t maximum_timeout_seconds=30) noexcept
 Mount a server-owned file for an already authorized client session.
RemoteFileMount MountRemoteFileWriter (std::string_view client_uuid, std::string_view path, std::uint16_t maximum_timeout_seconds=30) noexcept
 Mount a server-owned file for exclusive writing after application authorization.
void DisconnectClient (std::string_view uuid) noexcept
 Disconnect a client by UUID.
Safe::Optional< PeerAddress > GetPeerAddress (std::string_view uuid)
 Get the remote address for an active client session.
void DisconnectClientAfterReply (std::string_view uuid) noexcept
 Send the current handler's reply, then close and discard pending input.
virtual bool OnClientConnected (std::string_view uuid) noexcept
 Admit and initialize a newly registered application session.
virtual void OnClientDisconnected (std::string_view uuid) noexcept
 Release derived state when an application session is removed.
virtual StormByte::Safe::Binary OnDiscoveryQuery (const StormByte::Safe::Binary &query) const noexcept
 Decide whether to answer a discovery query.

Detailed Description

Abstract application server.

Forward declaration of the server owning its telemetry.

Listen socket and single-threaded event loop. Implement ProcessClientPacket(); optionally require TLS before starting the listener.

Note
Inheritance-oriented. Subclass required.

Constructor & Destructor Documentation

◆ Server() [1/3]

StormByte::Network::Server::Server ( DeserializePacketFunction deserialize_packet_function,
StormByte::Safe::Shared< Logger::Log > logger )

Construct with a packet factory and a logger.

Parameters
deserialize_packet_functionBuilds domain packets from wire data.
loggerDiagnostic logger.

◆ Server() [2/3]

StormByte::Network::Server::Server ( const Server & other)
delete

Copy constructor (deleted).

Parameters
otherServer that cannot be copied.

◆ Server() [3/3]

StormByte::Network::Server::Server ( Server && other)
noexcept

Stop the source before transferring its inactive state.

Parameters
otherServer whose state is transferred.
Precondition
Neither server is moved from its event loop or a packet worker.

◆ ~Server()

virtual StormByte::Network::Server::~Server ( )
virtualnoexcept

Destructor (joins threads, disconnects clients).

Member Function Documentation

◆ AllowIncomingOpcode()

virtual bool StormByte::Network::Server::AllowIncomingOpcode ( std::string_view uuid,
Transport::Packet::OpcodeType opcode ) const
protectedvirtualnoexcept

Admit an application opcode before its pipeline and factory run.

Parameters
uuidServer-assigned session identity.
opcodeIncoming application opcode.
Returns
True by default; false closes only this application session.

Runs on the event loop; synchronize state shared with workers. Frames coalesced with a handshake remain raw until the preceding handler completes. This hook then sees its updated session policy before any input transformation or packet factory executes for the next message.

◆ AllowOutgoingOpcode()

virtual bool StormByte::Network::Server::AllowOutgoingOpcode ( std::string_view uuid,
Transport::Packet::OpcodeType opcode ) const
protectedvirtualnoexcept

Admit a response opcode before output transformation.

Parameters
uuidServer-assigned session identity.
opcodeOutgoing application opcode.
Returns
True by default; false closes only this application session.

Runs on the event loop; synchronize state shared with workers.

◆ Announce()

bool StormByte::Network::Server::Announce ( const Connection::Protocol & protocol,
unsigned short discovery_port )
noexcept

Start listening for discovery queries on discovery_port.

Parameters
protocolAddress family (IPv4 broadcast or IPv6 multicast).
discovery_portUDP port to bind.
Returns
true when the listener is running.

Independent of the TCP Connect. Stop with StopAnnounce.

◆ ConfigureTLS()

bool StormByte::Network::Server::ConfigureTLS ( const Crypto::TLS::ServerConfiguration & configuration,
bool refresh_validation_time = true )
noexcept

Require TLS for new application and remote-file connections.

Parameters
configurationBorrowed identity, mTLS roots and policy copied synchronously.
refresh_validation_timeUse current time for each new session by default; false explicitly preserves the supplied client-certificate validation instant.
Returns
False while running or when validation fails, without replacing state.

Each accepted channel owns an independent incremental TLS session. OnClientConnected runs only after successful TLS authentication. Externally serialize configuration, connection, moves and destruction.

◆ Connect()

bool StormByte::Network::Server::Connect ( const Connection::Protocol & protocol,
std::string_view address,
const unsigned short & port )
overridevirtual

Bind, listen and start the accept thread.

Parameters
protocolAddress family.
addressBind address.
portPort number.
Returns
true on success.

Implements StormByte::Network::Endpoint.

◆ DisableTLS()

bool StormByte::Network::Server::DisableTLS ( )
noexcept

Restore plaintext while the server is stopped.

Returns
False unless disconnected.

◆ Disconnect()

void StormByte::Network::Server::Disconnect ( )
overridevirtualnoexcept

Stop accept, disconnect clients and close the listener.

Implements StormByte::Network::Endpoint.

◆ DisconnectClient()

void StormByte::Network::Server::DisconnectClient ( std::string_view uuid)
protectednoexcept

Disconnect a client by UUID.

Parameters
uuidClient UUID.

◆ DisconnectClientAfterReply()

void StormByte::Network::Server::DisconnectClientAfterReply ( std::string_view uuid)
protectednoexcept

Send the current handler's reply, then close and discard pending input.

Parameters
uuidSession handled by the calling packet worker.

Call before returning the rejection packet from ProcessClientPacket. Network does not interpret its opcode. No subsequent queued frame is transformed, deserialized or dispatched; closure follows output draining.

◆ GetPeerAddress()

Safe::Optional< PeerAddress > StormByte::Network::Server::GetPeerAddress ( std::string_view uuid)
protected

Get the remote address for an active client session.

Parameters
uuidServer-assigned session identity.
Returns
Peer address, or empty when the session is not active.

Safe to call from server callbacks and packet workers.

◆ MountRemoteFileReader()

RemoteFileMount StormByte::Network::Server::MountRemoteFileReader ( std::string_view client_uuid,
std::string_view path,
std::uint16_t maximum_timeout_seconds = 30 )
protectednoexcept

Mount a server-owned file for an already authorized client session.

Parameters
client_uuidClient session which owns this capability.
pathServer-local path selected by application policy.
maximum_timeout_secondsHeartbeat timeout in [3, 3600] seconds.
Returns
Authorized descriptor, or Unavailable when mounting failed.

◆ MountRemoteFileWriter()

RemoteFileMount StormByte::Network::Server::MountRemoteFileWriter ( std::string_view client_uuid,
std::string_view path,
std::uint16_t maximum_timeout_seconds = 30 )
protectednoexcept

Mount a server-owned file for exclusive writing after application authorization.

Parameters
client_uuidRequesting application session.
pathServer-local file path selected by application policy.
maximum_timeout_secondsHeartbeat timeout in [3, 3600] seconds.
Returns
Authorized descriptor, or Unavailable when mounting failed or another writer owns the path.

◆ OnClientConnected()

virtual bool StormByte::Network::Server::OnClientConnected ( std::string_view uuid)
protectedvirtualnoexcept

Admit and initialize a newly registered application session.

Parameters
uuidServer-assigned session identity, borrowed for this call.
Returns
True to continue packet processing; false to close the session.

Called on the event-loop thread before any packet is dispatched. The default accepts the session. Do not block waiting for network I/O or workers; perform an application login in ProcessClientPacket instead. Synchronize derived state shared with packet workers. Rejected sessions also receive OnClientDisconnected.

◆ OnClientDisconnected()

virtual void StormByte::Network::Server::OnClientDisconnected ( std::string_view uuid)
protectedvirtualnoexcept

Release derived state when an application session is removed.

Parameters
uuidRemoved session identity, borrowed for this call.

Called once on the event-loop thread, including server shutdown. The default does nothing. An already dispatched worker may still finish; derived handlers must not recreate authorization for a removed session. Do not wait for workers in this callback. Derived destructors must call Disconnect before destroying state used by these hooks or handlers.

◆ OnDiscoveryQuery()

virtual StormByte::Safe::Binary StormByte::Network::Server::OnDiscoveryQuery ( const StormByte::Safe::Binary & query) const
protectedvirtualnoexcept

Decide whether to answer a discovery query.

Parameters
queryOpaque query payload.
Returns
Reply bytes. Empty means do not answer.

◆ operator=() [1/2]

Server & StormByte::Network::Server::operator= ( const Server & other)
delete

Copy assignment (deleted).

Parameters
otherServer that cannot be copied.
Returns
Reference to this server (operation is deleted).

◆ operator=() [2/2]

Server & StormByte::Network::Server::operator= ( Server && other)
noexcept

Stop both servers before transferring inactive state.

Parameters
otherServer whose state is transferred.
Returns
Reference to this server.
Precondition
Neither server is moved from its event loop or a packet worker.

◆ Status()

Connection::Status StormByte::Network::Server::Status ( ) const
overridevirtualnoexcept

Listener / server status.

Returns
Status.

Implements StormByte::Network::Endpoint.

◆ StopAnnounce()

void StormByte::Network::Server::StopAnnounce ( )
noexcept

Stop the discovery listener.

◆ Telemetry()

StormByte::Safe::Shared< ServerTelemetry > StormByte::Network::Server::Telemetry ( ) const
noexcept

Shared live telemetry aggregated across this Server's sessions.

Returns
Server-owned aggregate counters and handler latency.

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