StormByte-Network 4.0.0
C++26 networking module of the StormByte suite
Loading...
Searching...
No Matches
client.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Network.
5 *
6 * StormByte-Network original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Network source in this
20 * repository. They do not cover other StormByte modules or any third-party
21 * material shipped with this repository (including everything under
22 * thirdparty/, and in particular the bundled StormByte Buffer tree), which
23 * remains under its own license.
24 *
25 * Neither license grants any patent rights. Any patent licenses required
26 * to use this software or third-party components must be obtained separately
27 * from the patent holders.
28 *
29 * StormByte-Network is distributed in the hope that it will be useful,
30 * but WITHOUT ANY WARRANTY; without even the implied warranty of
31 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
32 * GNU Lesser General Public License for more details.
33 *
34 * You should have received a copy of the GNU Lesser General Public License
35 * version 3 along with StormByte-Network. If not, see
36 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
37 *
38 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
39 */
40
41#pragma once
42
43#include <StormByte/crypto/tls/session.hxx>
48#include <StormByte/safe/atomic.hxx>
49#include <StormByte/safe/function.hxx>
50#include <StormByte/safe/mutex.hxx>
51#include <StormByte/safe/pointers.hxx>
52#include <StormByte/safe/string.hxx>
53
54#include <chrono>
55#include <string_view>
56
61namespace StormByte {
66 namespace Network {
71 namespace Connection {
76 class Client;
77
81 class Resolver;
82 }
83
88 namespace Socket {
92 class Client;
93 }
94
99 namespace Detail {
103 class TLSConfiguration;
104 }
105
125 public:
129 enum class Error {
130 InvalidTimeout,
131 NotConnected,
132 AlreadyConnected,
133 TimedOut,
134 Cancelled,
135 ResolverBusy,
137 TLS,
138 Packet,
139 Allocation
140 };
141
148
153 Client(const Client& other) = delete;
154
159 Client(Client&& other) noexcept;
160
164 virtual ~Client() noexcept;
165
171 Client& operator=(const Client& other) = delete;
172
178 Client& operator=(Client&& other) noexcept;
179
187 bool Connect(const Connection::Protocol& protocol, std::string_view address, const unsigned short& port) override;
188
201 Expected<void, Error> Connect(const Connection::Protocol& protocol, std::string_view address,
202 unsigned short port, std::chrono::milliseconds timeout);
203
214 Expected<void, Error> Connect(const Connection::Protocol& protocol, std::string_view address,
215 unsigned short port, std::chrono::milliseconds timeout, Safe::String& detail);
216
224 void Cancel() noexcept;
225
235 bool ConfigureTLS(const Crypto::TLS::ClientConfiguration& configuration,
236 bool refresh_validation_time = true) noexcept;
237
246 bool ConfigureTLS(const Crypto::TLS::ClientConfiguration& configuration,
247 Safe::String& detail, bool refresh_validation_time = true);
248
253 bool DisableTLS() noexcept;
254
262 void Disconnect() noexcept override;
263
268 Connection::Status Status() const noexcept override;
269
274 StormByte::Safe::Shared<ClientTelemetry> Telemetry() const noexcept;
275
285 bool Discover(const Connection::Protocol& protocol, unsigned short discovery_port,
286 std::chrono::milliseconds timeout,
287 StormByte::Safe::Function<bool(const DiscoveryReply&)> on_reply) noexcept;
288
289
290 protected:
297 virtual bool AllowIncomingOpcode(std::string_view uuid, Transport::Packet::OpcodeType opcode) const noexcept;
298
305 virtual bool AllowOutgoingOpcode(std::string_view uuid, Transport::Packet::OpcodeType opcode) const noexcept;
306
311 virtual StormByte::Safe::Binary MakeDiscoveryQuery() const noexcept;
312
320 virtual bool InterpretDiscoveryReply(const StormByte::Safe::Binary& reply,
321 StormByte::Safe::String& address, unsigned short& port) const noexcept;
322
323
329 PacketPointer Send(const Transport::Packet& packet) noexcept;
330
340 Expected<PacketPointer, Error> Send(const Transport::Packet& packet, std::chrono::milliseconds timeout);
341
348
355
356 private:
360 void DropConnection() noexcept;
361
362 Safe::Mutex m_operation_mutex;
363 mutable Safe::Mutex m_state_mutex;
364 Safe::Atomic<bool> m_cancelled{false};
365 Safe::Shared<Socket::Client> m_active_socket;
369 Safe::String m_remote_address;
371 Safe::Mutex m_remote_file_mutex;
374 };
375 }
376}
377
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
Cumulative telemetry owned by one Client instance.
Definition client_telemetry.hxx:71
Abstract application client.
Definition client.hxx:124
void Disconnect() noexcept override
Cancel I/O and disconnect if connected.
PacketPointer Send(const Transport::Packet &packet) noexcept
Send packet and return the response (or nullptr).
virtual ~Client() noexcept
Disconnect and release Safe owners inside Network.
RemoteFileWriterHandle CreateRemoteFileWriter(const RemoteFileMount &mount) noexcept
Attach a writer to an application-authorized exclusive remote mount.
StormByte::Safe::Shared< ClientTelemetry > Telemetry() const noexcept
Shared live telemetry for this Client instance only.
bool ConfigureTLS(const Crypto::TLS::ClientConfiguration &configuration, bool refresh_validation_time=true) noexcept
Require TLS for subsequent application and remote-file connections.
bool DisableTLS() noexcept
Restore plaintext for future connections while disconnected.
Client(const Client &other)=delete
Copy constructor (deleted).
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.
Error
Explicit request/connect failures; failed streams are never replayed.
Definition client.hxx:129
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.
Client(Client &&other) noexcept
Transfer Safe owners inside Network without moving the mutex.
Client(DeserializePacketFunction deserialize_packet_function, StormByte::Safe::Shared< Logger::Log > logger)
Construct with a packet factory and a logger.
RemoteFileReaderHandle CreateRemoteFileReader(const RemoteFileMount &mount) noexcept
Attach a reader to an application-authorized remote file mount.
virtual StormByte::Safe::Binary MakeDiscoveryQuery() const noexcept
Build the opaque discovery query.
Connection::Status Status() const noexcept override
Current connection status.
void Cancel() noexcept
Cancel the active operation and invalidate its application stream.
virtual bool AllowOutgoingOpcode(std::string_view uuid, Transport::Packet::OpcodeType opcode) const noexcept
Admit an outgoing opcode before applying the output pipeline.
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.
virtual bool AllowIncomingOpcode(std::string_view uuid, Transport::Packet::OpcodeType opcode) const noexcept
Admit a received opcode before transformation and deserialization.
Caller-owned callback that builds a packet from opcode and payload.
Definition typedefs.hxx:143
Endpoint(DeserializePacketFunction deserialize_packet_function, StormByte::Safe::Shared< Logger::Log > logger) noexcept
Construct with a packet factory and a logger.
Public, validated descriptor for attaching to one remote file channel.
Definition remote_file_mount.hxx:69
Connection namespace.
Protocol
Address family for sockets.
Definition protocol.hxx:60
@ IPv4
IPv4 (AF_INET).
Definition protocol.hxx:61
Private native transport implementation.
Transport namespace.
Network module of the StormByte suite.
StormByte::Safe::Unique< BufferedRemoteFileReader > RemoteFileReaderHandle
Base-heap owner movable to Unique<Buffer::IO::BufferedLocationReader> without slicing.
Definition remote_file.hxx:387
StormByte::Safe::Unique< BufferedRemoteFileWriter > RemoteFileWriterHandle
Base-heap owner movable to Unique<Buffer::IO::BufferedLocationWriter> without slicing.
Definition remote_file.hxx:392
StormByte::Safe::Shared< Transport::Packet > PacketPointer
Base-heap shared packet pointer.
Definition typedefs.hxx:132
Root namespace of the StormByte suite.
std::conditional_t< Type::Reference< T >, std::expected< std::reference_wrapper< std::remove_reference_t< T > >, Safe::Shared< E > >, std::expected< T, Safe::Shared< E > > > Expected
STL namespace.
One datagram received during discovery.
Definition discovery.hxx:65
#define STORMBYTE_NETWORK_PUBLIC
Definition visibility.h:51