Abstract application client. More...
#include <StormByte/network/client.hxx>


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. | |
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.
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.
|
strong |
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. |
| StormByte::Network::Client::Client | ( | DeserializePacketFunction | deserialize_packet_function, |
| StormByte::Safe::Shared< Logger::Log > | logger ) |
Construct with a packet factory and a logger.
| deserialize_packet_function | Builds domain packets from wire data. |
| logger | Diagnostic logger. |
|
delete |
Copy constructor (deleted).
| other | Client that cannot be copied. |
|
noexcept |
|
virtualnoexcept |
|
protectedvirtualnoexcept |
Admit a received opcode before transformation and deserialization.
| uuid | Local connection identity, borrowed during the call. |
| opcode | Incoming application opcode. |
|
protectedvirtualnoexcept |
Admit an outgoing opcode before applying the output pipeline.
| uuid | Local connection identity, borrowed during the call. |
| opcode | Outgoing application opcode. |
|
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.
|
noexcept |
Require TLS for subsequent application and remote-file connections.
| configuration | Borrowed Crypto inputs, deeply copied during this call. |
| refresh_validation_time | Use current time for each new session by default; false explicitly preserves the supplied instant for offline validation. |
Requires an explicit expected server identity. Retained across reconnects. Externally serialize configuration, connection, moves and destruction.
| 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.
| configuration | Borrowed Crypto inputs, copied during this call. |
| detail | Output cleared on entry; failure explanation. |
| refresh_validation_time | Refresh time per new session. |
| StormByte::Safe::AllocationError | Explanation storage cannot be allocated. |
|
overridevirtual |
Connect to a remote host with a ten-second total default budget.
| protocol | Address family. |
| address | Hostname or IP borrowed for this call, without embedded nulls. |
| port | Port number. |
Implements StormByte::Network::Endpoint.
| 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.
| protocol | Address family. |
| address | Borrowed hostname or IP. |
| port | Destination port. |
| timeout | Total budget; zero expires immediately, max means unlimited. |
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.
| 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.
| protocol | Address family. |
| address | Borrowed hostname or IP. |
| port | Destination port. |
| timeout | Total operation budget. |
| detail | Output cleared on entry; populated for TLS setup/authentication failure. |
Output is caller-owned and survives failed connection cleanup.
|
protectednoexcept |
Attach a reader to an application-authorized remote file mount.
| mount | Public mount descriptor decoded by the application factory. |
|
protectednoexcept |
Attach a writer to an application-authorized exclusive remote mount.
| mount | Public mount descriptor decoded by the application factory. |
|
noexcept |
Restore plaintext for future connections while disconnected.
|
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.
|
noexcept |
Send a discovery query and invoke on_reply for each response.
| protocol | Address family. |
| discovery_port | UDP port where servers announce. |
| timeout | Maximum time to wait for replies. |
| on_reply | Called for each datagram. Return true to stop, false to continue. |
Uses MakeDiscoveryQuery() as the payload. Empty query does not send.
|
protectedvirtualnoexcept |
Interpret a discovery reply into a TCP endpoint.
| reply | Opaque reply payload. |
| address | Filled with the TCP address when accepted. |
| port | Filled with the TCP port when accepted. |
|
protectedvirtualnoexcept |
Build the opaque discovery query.
Copy assignment (deleted).
| other | Client that cannot be copied. |
|
protectednoexcept |
Send packet and return the response (or nullptr).
| packet | Request packet. |
|
protected |
Send and receive one packet under a single total budget.
| packet | Borrowed request. |
| timeout | Total send/header/payload budget; max means unlimited. |
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.
|
overridevirtualnoexcept |
|
noexcept |
Shared live telemetry for this Client instance only.