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>
44#include <StormByte/expected.hxx>
46#include <StormByte/safe/atomic.hxx>
47#include <StormByte/safe/binary.hxx>
48#include <StormByte/safe/pointers.hxx>
49#include <StormByte/safe/string.hxx>
50#include <StormByte/safe/vector.hxx>
51
52#include <chrono>
53#include <cstddef>
54#include <span>
55#include <string_view>
56
61namespace StormByte {
66 namespace Network {
71 namespace Connection {
75 class Resolver;
76 }
81 namespace Detail {
85 class TLSConfiguration;
86 }
91 namespace HTTP {
111
122
134 Header(std::string_view name = {}, std::string_view value = {});
139 Header(const Header& other);
144 Header(Header&& other) noexcept;
148 ~Header() noexcept;
154 Header& operator=(const Header& other);
160 Header& operator=(Header&& other) noexcept;
161 Safe::String name;
162 Safe::String value;
163 };
164 }
165 }
166}
167
169
174namespace StormByte {
179 namespace Network {
184 namespace HTTP {
185
198 explicit Request(std::string_view url = {});
203 Request(const Request& other);
208 Request(Request&& other) noexcept;
212 ~Request() noexcept;
218 Request& operator=(const Request& other);
224 Request& operator=(Request&& other) noexcept;
225 Safe::String url;
226 Safe::String method;
227 Safe::Vector<Header> headers;
228 Safe::Binary body;
229 };
230
274
288 public:
292 Receiver() noexcept = default;
297 Receiver(const Receiver& other) noexcept = default;
302 Receiver(Receiver&& other) noexcept = default;
306 virtual ~Receiver() noexcept;
312 Receiver& operator=(const Receiver& other) noexcept = default;
318 Receiver& operator=(Receiver&& other) noexcept = default;
325 virtual bool Begin(unsigned short status, const Safe::Vector<Header>& headers) = 0;
331 virtual bool Write(std::span<const std::byte> bytes) = 0;
332 };
333
340 struct Options {
344 Options() noexcept = default;
345
350 Options(const Options& other) noexcept = default;
351
356 Options(Options&& other) noexcept = default;
357
361 ~Options() noexcept = default;
362
368 Options& operator=(const Options& other) noexcept = default;
369
375 Options& operator=(Options&& other) noexcept = default;
376
378 std::chrono::milliseconds timeout{30000};
382 Receiver* receiver{nullptr};
383 ByteSize body_bytes{16 * 1024 * 1024};
384 ByteSize wire_bytes{32 * 1024 * 1024};
385 ByteSize http2_bytes{1024 * 1024};
388 };
389
400 public:
410 Client(const Client& other) = delete;
416 Client(Client&& other) noexcept;
420 ~Client() noexcept;
426 Client& operator=(const Client& other) = delete;
432 Client& operator=(Client&& other) noexcept;
442 bool ConfigureTLS(const Crypto::TLS::ClientConfiguration& configuration,
443 bool refresh_validation_time = true) noexcept;
444
453 bool ConfigureTLS(const Crypto::TLS::ClientConfiguration& configuration,
454 Safe::String& detail, bool refresh_validation_time = true);
455
466 Expected<Response, Error> Execute(const Request& request, const Options& options = {});
467
478 Expected<Response, Error> Execute(const Request& request, const Options& options, Safe::String& detail);
479
480 private:
483 };
484 }
485 }
486}
487
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
Synchronous single-request-per-connection client.
Definition client.hxx:399
Client(Client &&other) noexcept
Transfer resolver and immutable TLS policy; moved-from clients can be reassigned but Execute returns ...
bool ConfigureTLS(const Crypto::TLS::ClientConfiguration &configuration, bool refresh_validation_time=true) noexcept
Deep-copy custom trust, identity, revocation and mTLS inputs.
Expected< Response, Error > Execute(const Request &request, const Options &options, Safe::String &detail)
Execute with an owned TLS failure explanation.
Expected< Response, Error > Execute(const Request &request, const Options &options={})
Execute one bounded request, closing its connection on all exits.
Client()
Allocate a managed resolver inside Network.
Client(const Client &other)=delete
Copying a resolver owner is disabled.
~Client() noexcept
Join retained DNS work and release provider-owned policy.
Borrowed streaming consumer of the final response body.
Definition client.hxx:287
virtual bool Begin(unsigned short status, const Safe::Vector< Header > &headers)=0
Accept or decline the final response before its body.
virtual bool Write(std::span< const std::byte > bytes)=0
Consume the next nonempty body chunk.
Receiver() noexcept=default
Construct a stateless receiver base.
Connection namespace.
Network-owned endpoint implementation state.
Bounded HTTP client API; no HTTP server or HTTP/3.
Protocol
Protocol selection.
Definition client.hxx:117
@ Automatic
HTTP/1 cleartext, h2/http1.1 HTTPS ALPN.
Definition client.hxx:118
@ HTTP1
HTTP/1.1 only.
Definition client.hxx:119
Error
Typed terminal failures; no failed request is replayed.
Definition client.hxx:95
@ TLS
TLS configuration, authentication or engine failure.
Definition client.hxx:104
@ LimitExceeded
An explicit request/response bound was exceeded.
Definition client.hxx:99
@ Allocation
Provider-side allocation or callback construction failed.
Definition client.hxx:108
@ Truncated
Incomplete message or bare TCP EOF on authenticated TLS.
Definition client.hxx:106
@ InvalidOptions
Invalid limits, deadline, protocol or moved-from client.
Definition client.hxx:98
@ InvalidURL
Invalid or unsupported absolute URL.
Definition client.hxx:96
@ ResolverBusy
Previous managed DNS work is still running.
Definition client.hxx:102
@ TimedOut
Total request deadline expired.
Definition client.hxx:100
@ Cancelled
Borrowed cancellation flag was set.
Definition client.hxx:101
@ Rejected
The streaming Receiver declined the response or failed.
Definition client.hxx:109
@ InvalidRequest
Invalid method, field or unsupported request feature.
Definition client.hxx:97
@ HTTP2
HTTP/2 engine, frame, reset or GOAWAY failure.
Definition client.hxx:107
Transport namespace.
Network module of the StormByte suite.
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 header occurrence, preserving duplicates and received order.
Definition client.hxx:127
Header(const Header &other)
Independently copy both fields.
Header(Header &&other) noexcept
Transfer both fields, leaving empty source text.
Safe::String value
Value, without CR/LF.
Definition client.hxx:162
~Header() noexcept
Release provider-owned text.
Safe::String name
Field name, without colon.
Definition client.hxx:161
Header(std::string_view name={}, std::string_view value={})
Copy borrowed header text into provider-owned storage.
Scalar request limits.
Definition client.hxx:340
Receiver * receiver
Borrowed until Execute returns; streams the final body.
Definition client.hxx:382
ByteSize wire_bytes
Maximum incoming wire plaintext.
Definition client.hxx:384
ByteSize header_bytes
Aggregate decoded headers, status and trailer bytes.
Definition client.hxx:380
Protocol protocol
Protocol policy.
Definition client.hxx:377
Size header_fields
Aggregate field count.
Definition client.hxx:381
std::chrono::milliseconds timeout
One total DNS-to-body deadline.
Definition client.hxx:378
ByteSize http2_bytes
Maximum live native HTTP/2 session allocation.
Definition client.hxx:385
Size informational_responses
Maximum interim responses.
Definition client.hxx:387
ByteSize body_bytes
Maximum buffered or streamed body in either direction.
Definition client.hxx:383
const Safe::Atomic< bool > * cancellation
Borrowed until Execute returns.
Definition client.hxx:379
Options() noexcept=default
Construct default scalar limits without allocation.
ByteSize url_bytes
Maximum URL bytes.
Definition client.hxx:386
Fully buffered request.
Definition client.hxx:192
Safe::String method
Case-sensitive method token; defaults to GET.
Definition client.hxx:226
Request(const Request &other)
Independently copy the request.
Safe::Binary body
Byte-exact request body, including NUL bytes.
Definition client.hxx:228
~Request() noexcept
Release all provider-owned fields.
Request(std::string_view url={})
Construct a GET request for a borrowed absolute URL.
Safe::Vector< Header > headers
Ordered duplicate-preserving user headers.
Definition client.hxx:227
Safe::String url
Absolute ASCII URL; fragments are rejected.
Definition client.hxx:225
Request(Request &&other) noexcept
Transfer request ownership.
Fully buffered final response; informational responses are consumed, 3xx is returned unchanged,...
Definition client.hxx:237
Safe::Vector< Header > trailers
Validated trailing fields.
Definition client.hxx:271
Safe::Binary body
Byte-exact entity body after transfer framing removal.
Definition client.hxx:272
Response(Response &&other) noexcept
Transfer response ownership.
~Response() noexcept
Release provider-owned fields.
Response(const Response &other)
Independently copy the response.
unsigned short status
Final three-digit status.
Definition client.hxx:268
Safe::Vector< Header > headers
Final fields, preserving duplicates.
Definition client.hxx:270
Response()
Construct an empty response.
Protocol protocol
Actual HTTP wire protocol.
Definition client.hxx:269
#define STORMBYTE_NETWORK_PUBLIC
Definition visibility.h:51