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

Abstract application client. More...

#include <StormByte/network/client.hxx>

Inheritance diagram for StormByte::Network::Client:
Collaboration diagram for StormByte::Network::Client:

Public Types

enum class  Error {
  InvalidTimeout , NotConnected , AlreadyConnected , TimedOut ,
  Cancelled , ResolverBusy , Transport , TLS ,
  Packet , Allocation
}
 Explicit request/connect failures; failed streams are never replayed. More...

Public Member Functions

 Client (DeserializePacketFunction deserialize_packet_function, StormByte::Safe::Shared< Logger::Log > logger)
 Construct with a packet factory and a logger.
 Client (const Client &other)=delete
 Copy constructor (deleted).
 Client (Client &&other) noexcept
 Transfer Safe owners inside Network without moving the mutex.
virtual ~Client () noexcept
 Disconnect and release Safe owners inside Network.
Client & operator= (const Client &other)=delete
 Copy assignment (deleted).
Client & operator= (Client &&other) noexcept
 Disconnect this client before transferring Safe owners in Network.
bool Connect (const Connection::Protocol &protocol, std::string_view address, const unsigned short &port) override
 Connect to a remote host with a ten-second total default budget.
Expected< void, Error > Connect (const Connection::Protocol &protocol, std::string_view address, unsigned short port, std::chrono::milliseconds timeout)
 Resolve, connect and authenticate using one total time budget.
Expected< void, Error > Connect (const Connection::Protocol &protocol, std::string_view address, unsigned short port, std::chrono::milliseconds timeout, Safe::String &detail)
 Connect with a copied TLS failure explanation.
void Cancel () noexcept
 Cancel the active operation and invalidate its application stream.
bool ConfigureTLS (const Crypto::TLS::ClientConfiguration &configuration, bool refresh_validation_time=true) noexcept
 Require TLS for subsequent application and remote-file connections.
bool ConfigureTLS (const Crypto::TLS::ClientConfiguration &configuration, Safe::String &detail, bool refresh_validation_time=true)
 Configure TLS with an owned explanation on failure.
bool DisableTLS () noexcept
 Restore plaintext for future connections while disconnected.
void Disconnect () noexcept override
 Cancel I/O and disconnect if connected.
Connection::Status Status () const noexcept override
 Current connection status.
StormByte::Safe::Shared< ClientTelemetry > Telemetry () const noexcept
 Shared live telemetry for this Client instance only.
bool Discover (const Connection::Protocol &protocol, unsigned short discovery_port, std::chrono::milliseconds timeout, StormByte::Safe::Function< bool(const DiscoveryReply &)> on_reply) noexcept
 Send a discovery query and invoke on_reply for each response.

Protected Member Functions

virtual bool AllowIncomingOpcode (std::string_view uuid, Transport::Packet::OpcodeType opcode) const noexcept
 Admit a received opcode before transformation and deserialization.
virtual bool AllowOutgoingOpcode (std::string_view uuid, Transport::Packet::OpcodeType opcode) const noexcept
 Admit an outgoing opcode before applying the output pipeline.
virtual StormByte::Safe::Binary MakeDiscoveryQuery () const noexcept
 Build the opaque discovery query.
virtual bool InterpretDiscoveryReply (const StormByte::Safe::Binary &reply, StormByte::Safe::String &address, unsigned short &port) const noexcept
 Interpret a discovery reply into a TCP endpoint.
PacketPointer Send (const Transport::Packet &packet) noexcept
 Send packet and return the response (or nullptr).
Expected< PacketPointer, Error > Send (const Transport::Packet &packet, std::chrono::milliseconds timeout)
 Send and receive one packet under a single total budget.
RemoteFileReaderHandle CreateRemoteFileReader (const RemoteFileMount &mount) noexcept
 Attach a reader to an application-authorized remote file mount.
RemoteFileWriterHandle CreateRemoteFileWriter (const RemoteFileMount &mount) noexcept
 Attach a writer to an application-authorized exclusive remote mount.

Detailed Description

Abstract application client.

Forward declaration of the client owning its telemetry.

Derive and use protected Send() for request/response. ConfigureTLS enables authenticated TLS before connecting, including every remote-file channel.

Note
Inheritance-oriented. Not for direct generic use without a subclass.

All owned fields use Safe handles; construction, moves, assignment and destruction run inside Network. Allocate an exact derived type through its provider's Safe factory when sharing ownership across modules; the base registration does not certify derived state. Keep Base, Network, Crypto, logger, packet and callback providers loaded until their objects are released. Connect and requests serialize internally; Cancel, Disconnect, Status and Telemetry may be used concurrently. Externally synchronize moves, destruction and caller-owned callback state. Opcode UUIDs and Connect addresses are synchronous borrowed views.

Member Enumeration Documentation

◆ Error

Explicit request/connect failures; failed streams are never replayed.

Enumerator
InvalidTimeout 

Negative budgets are invalid.

NotConnected 

No usable application connection.

AlreadyConnected 

Connect would replace a live stream.

TimedOut 

The total operation budget expired.

Cancelled 

Cancel or Disconnect interrupted this operation.

ResolverBusy 

A previous OS DNS lookup is still running.

Transport 

DNS, native I/O, EOF or incomplete framing.

TLS 

TLS configuration or authentication failed.

Packet 

Opcode policy, transformation or deserialization failed.

Allocation 

Network could not allocate operation state.

Constructor & Destructor Documentation

◆ Client() [1/3]

StormByte::Network::Client::Client ( 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.

◆ Client() [2/3]

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

Copy constructor (deleted).

Parameters
otherClient that cannot be copied.

◆ Client() [3/3]

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

Transfer Safe owners inside Network without moving the mutex.

Parameters
otherClient whose state is transferred.

◆ ~Client()

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

Disconnect and release Safe owners inside Network.

Member Function Documentation

◆ AllowIncomingOpcode()

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

Admit a received opcode before transformation and deserialization.

Parameters
uuidLocal connection identity, borrowed during the call.
opcodeIncoming application opcode.
Returns
True by default; false closes the application connection.

◆ AllowOutgoingOpcode()

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

Admit an outgoing opcode before applying the output pipeline.

Parameters
uuidLocal connection identity, borrowed during the call.
opcodeOutgoing application opcode.
Returns
True by default; false prevents sending and closes the connection.

◆ Cancel()

void StormByte::Network::Client::Cancel ( )
noexcept

Cancel the active operation and invalidate its application stream.

Thread-safe against Connect, Send, Status and Disconnect. Shuts down connected I/O without closing/reusing a handle concurrently. Cancellation is sticky until the next Connect; no failed frame is replayed. Remote-file channels retain their independent lifecycle.

◆ ConfigureTLS() [1/2]

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

Require TLS for subsequent application and remote-file connections.

Parameters
configurationBorrowed Crypto inputs, deeply copied during this call.
refresh_validation_timeUse current time for each new session by default; false explicitly preserves the supplied instant for offline validation.
Returns
False when connected or configuration validation fails; no state changes.

Requires an explicit expected server identity. Retained across reconnects. Externally serialize configuration, connection, moves and destruction.

◆ ConfigureTLS() [2/2]

bool StormByte::Network::Client::ConfigureTLS ( const Crypto::TLS::ClientConfiguration & configuration,
Safe::String & detail,
bool refresh_validation_time = true )

Configure TLS with an owned explanation on failure.

Parameters
configurationBorrowed Crypto inputs, copied during this call.
detailOutput cleared on entry; failure explanation.
refresh_validation_timeRefresh time per new session.
Returns
Whether configuration succeeded; prior policy survives failure.
Exceptions
StormByte::Safe::AllocationErrorExplanation storage cannot be allocated.

◆ Connect() [1/3]

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

Connect to a remote host with a ten-second total default budget.

Parameters
protocolAddress family.
addressHostname or IP borrowed for this call, without embedded nulls.
portPort number.
Returns
true on success.

Implements StormByte::Network::Endpoint.

◆ Connect() [2/3]

Expected< void, Error > StormByte::Network::Client::Connect ( const Connection::Protocol & protocol,
std::string_view address,
unsigned short port,
std::chrono::milliseconds timeout )

Resolve, connect and authenticate using one total time budget.

Parameters
protocolAddress family.
addressBorrowed hostname or IP.
portDestination port.
timeoutTotal budget; zero expires immediately, max means unlimited.
Returns
Completion or typed failure; a failed connection is discarded.

OS DNS is not preemptible: a stopped lookup keeps the managed slot busy until it finishes, and destruction joins it. User callbacks cannot be preempted. Connect and Send serialize; moves and destruction require external lifetime synchronization, including against Cancel.

◆ Connect() [3/3]

Expected< void, Error > StormByte::Network::Client::Connect ( const Connection::Protocol & protocol,
std::string_view address,
unsigned short port,
std::chrono::milliseconds timeout,
Safe::String & detail )

Connect with a copied TLS failure explanation.

Parameters
protocolAddress family.
addressBorrowed hostname or IP.
portDestination port.
timeoutTotal operation budget.
detailOutput cleared on entry; populated for TLS setup/authentication failure.
Returns
The same typed outcome as the existing timed overload.

Output is caller-owned and survives failed connection cleanup.

◆ CreateRemoteFileReader()

RemoteFileReaderHandle StormByte::Network::Client::CreateRemoteFileReader ( const RemoteFileMount & mount)
protectednoexcept

Attach a reader to an application-authorized remote file mount.

Parameters
mountPublic mount descriptor decoded by the application factory.
Returns
Caller-owned remote reader, or an empty handle on failure.

◆ CreateRemoteFileWriter()

RemoteFileWriterHandle StormByte::Network::Client::CreateRemoteFileWriter ( const RemoteFileMount & mount)
protectednoexcept

Attach a writer to an application-authorized exclusive remote mount.

Parameters
mountPublic mount descriptor decoded by the application factory.
Returns
Caller-owned remote writer, or an empty handle on failure.

◆ DisableTLS()

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

Restore plaintext for future connections while disconnected.

Returns
False while an application or file channel remains attached.

◆ Disconnect()

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

Cancel I/O and disconnect if connected.

Nonblocking when an operation owns the stream: that operation releases it on return. Safe from packet callbacks, like Cancel and Status. Other client calls must not reenter from callbacks. Destruction still requires all calls, including callbacks and cancellation, to have returned.

Implements StormByte::Network::Endpoint.

◆ Discover()

bool StormByte::Network::Client::Discover ( const Connection::Protocol & protocol,
unsigned short discovery_port,
std::chrono::milliseconds timeout,
StormByte::Safe::Function< bool(const DiscoveryReply &)> on_reply )
noexcept

Send a discovery query and invoke on_reply for each response.

Parameters
protocolAddress family.
discovery_portUDP port where servers announce.
timeoutMaximum time to wait for replies.
on_replyCalled for each datagram. Return true to stop, false to continue.
Returns
true if the query was sent. Does not imply a reply was received.

Uses MakeDiscoveryQuery() as the payload. Empty query does not send.

◆ InterpretDiscoveryReply()

virtual bool StormByte::Network::Client::InterpretDiscoveryReply ( const StormByte::Safe::Binary & reply,
StormByte::Safe::String & address,
unsigned short & port ) const
protectedvirtualnoexcept

Interpret a discovery reply into a TCP endpoint.

Parameters
replyOpaque reply payload.
addressFilled with the TCP address when accepted.
portFilled with the TCP port when accepted.
Returns
true if this reply identifies a usable server.

◆ MakeDiscoveryQuery()

virtual StormByte::Safe::Binary StormByte::Network::Client::MakeDiscoveryQuery ( ) const
protectedvirtualnoexcept

Build the opaque discovery query.

Returns
Query bytes. Empty means discovery is not used.

◆ operator=() [1/2]

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

Disconnect this client before transferring Safe owners in Network.

Parameters
otherClient whose state is transferred.
Returns
Reference to this client.

◆ operator=() [2/2]

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

Copy assignment (deleted).

Parameters
otherClient that cannot be copied.
Returns
Reference to this client (operation is deleted).

◆ Send() [1/2]

PacketPointer StormByte::Network::Client::Send ( const Transport::Packet & packet)
protectednoexcept

Send packet and return the response (or nullptr).

Parameters
packetRequest packet.
Returns
Response, or nullptr on error.

◆ Send() [2/2]

Expected< PacketPointer, Error > StormByte::Network::Client::Send ( const Transport::Packet & packet,
std::chrono::milliseconds timeout )
protected

Send and receive one packet under a single total budget.

Parameters
packetBorrowed request.
timeoutTotal send/header/payload budget; max means unlimited.
Returns
Response or distinct failure; failure discards the stream.

Includes pipeline and packet callbacks, which are synchronous and cannot be preempted. Expiry/cancellation is checked on their return. Legacy Send keeps an unlimited budget and returns an empty handle on failure.

◆ Status()

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

Current connection status.

Returns
Status.

Implements StormByte::Network::Endpoint.

◆ Telemetry()

StormByte::Safe::Shared< ClientTelemetry > StormByte::Network::Client::Telemetry ( ) const
noexcept

Shared live telemetry for this Client instance only.

Returns
Client-owned counters and request latency.

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