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

Multiplatform C++26 CMake License: LGPL v3 or commercial CI Sponsor

StormByte-Network is the C++26 networking module of the StormByte suite.

It depends on StormByte Base, Logger and System 3.0.0, Buffer 4.0.0 and Crypto 3.1.0.

It is not a thin socket wrapper. You inherit Client or Server, define packets, and optionally configure authenticated Crypto TLS. POSIX and Winsock, framing, event-driven I/O and bounded packet processing stay private.

Table of Contents

Repository

Documentation

Installation

git clone https://github.com/StormByte-Suite/StormByte-Network.git
cd StormByte-Network
cmake -S . -B build-install -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON \
-DWITH_NGHTTP2=BUNDLED \
-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
cmake --build build-install -j
cmake --install build-install

BUILD_SHARED_LIBS defaults to ON; use -DBUILD_SHARED_LIBS=OFF for a static build. WITH_NGHTTP2 defaults to BUNDLED, which builds the pinned nghttp2 1.70.0 submodule as a private static dependency; SYSTEM uses an installed nghttp2 and fails explicitly if its headers/library are missing. Initialize source dependencies with git submodule update --init --recursive. Needs StormByte-BuildMaster >= 2.1.5. Configure downloads the StormByte 3.0.0 release archives in BUNDLED mode, except Crypto 3.0.2. There are no StormByte source submodules. BuildMaster is the installed package when it is >= 2.1.5, otherwise the buildmaster submodule. -DENABLE_LTO=ON and -DENABLE_PGO=ON match the release builds. macOS is Apple Clang only.

CMake package

After installing Network and its StormByte dependencies, add the installed CMake modules directory to CMAKE_MODULE_PATH and link the imported target:

list(PREPEND CMAKE_MODULE_PATH "${STORMBYTE_PREFIX}/share/cmake/Modules")
find_package(StormByte REQUIRED COMPONENTS Network)
target_link_libraries(my_app PRIVATE StormByte::Network)

Private TLS transport

The private socket adapter drives Crypto's TLS 1.3 buffer session without including or linking OpenSSL directly. DNS, connect, authentication and subsequent I/O can share one absolute deadline and a borrowed cancellation flag. Crypto validates peer identity and trust before application data is accepted; the HTTP client negotiates HTTP/1.1 or HTTP/2 through ALPN. Responses are buffered by default; an optional HTTP::Receiver streams the final body chunk by chunk instead, for example to write a large download to disk with progress.

TLS failures, timeout and cancellation abandon the connection instead of replaying partially consumed plaintext/ciphertext. Bare TCP EOF is rejected as truncation; only TLS close-notify represents authenticated EOF. Shutdown exchanges close-notify within the supplied deadline.

For an owned explanation that survives failed-session cleanup, pass a Safe::String output to HTTP::Client::Execute(request, options, detail) or Client::Connect(protocol, address, port, timeout, detail). Client configuration also offers ConfigureTLS(configuration, detail, refresh_validation_time = true). Outputs are cleared at entry: requests/connections populate them only for TLS failures (and HTTP's unnotified TLS EOF), not unrelated transport errors, timeouts or cancellation. Setup failures use Crypto's static category description; authentication/record failures retain its specific engine detail. Existing overloads, typed errors and public class layouts remain unchanged. Application, server and remote-file transports also log TLS explanations; HTTP does not write diagnostics itself. Keep diagnostics separate from payloads; they contain no certificate bodies, keys or application data.

TLSTransportTest uses ephemeral loopback ports, Crypto sessions and offline certificates under test/fixtures/tls. The deliberately disposable server key is test data only; never use it as a credential or trust these certificates outside the test. The CA signing key was destroyed. Validation uses a fixed instant inside the certificates' validity, so tests do not expire with wall-clock time. Leaf certificates have 365-day validity to comply with macOS native TLS policy; the disposable CA certificates retain longer validity. OpenSSL's CLI was used only to generate these fixtures, not to build or run tests. The nine test cases cover fragmented TLS records, HTTP/2 and HTTP/1.1 ALPN selection (including a peer without ALPN), a byte-for-byte 512 KiB round trip, identity/trust and malformed-record rejection, invalid states, deadline/cancellation, backpressure, truncated EOF and orderly shutdown.

These examples use ccache; install it or omit the two compiler-launcher options when it is unavailable.

Why StormByte-Network

Goal How it is achieved
Inherit, don't wrap sockets Client / Server are abstract application endpoints.
Framed messages Transport::Packet + private Frame (opcode, size, payload).
Authenticated TLS Optional pre-connect TLS 1.3 for application and remote-file channels.
IPv4 and IPv6 Connection::Protocol.
Cross-platform POSIX and Winsock behind Socket / Handler.

Features

  • Abstract Endpoint, Client, Server
  • Packet factory (DeserializePacketFunction)
  • Connection status, read/write results
  • Request/response (Send) and fire-and-forget (Reply)
  • Server event loop with bounded packet-handler workers
  • Per-session in-flight ordering, bounded output buffering and backpressure handling
  • Input and output pipeline processing applies uniformly to every packet payload
  • Authorized, file-like remote readers and exclusive writers over private TCP channels
  • Discovery via Server::Announce / Client::Discover (IPv4 broadcast or IPv6 multicast, same API)

Dependencies

Dependency Required Version Role
StormByte (base) 3.0.0 Expected, Safe ownership/containers/synchronization/threads, Size, ByteSize, visibility
StormByte-Buffer 4.0.0 FIFO, Pipeline, Consumer, ReadOnly/WriteOnly, configurable remote-file transfers
StormByte-Crypto 3.1.0 Buffer-driven TLS 1.3 sessions, certificate verification, trust policies and failure explanations
StormByte-Logger 3.0.0 Diagnostics
StormByte-System 3.0.0 Calling-thread utilities
nghttp2 1.70.0 when bundled Private HTTP/2 protocol engine; WITH_NGHTTP2=BUNDLED is the default, SYSTEM uses an installed library

The rest of the suite

Module Role API
Base Exceptions, Expected, serialization, UUID, concepts, safe text and pointer abstractions /StormByte
Buffer FIFO, SharedFIFO, Ring, Producer/Consumer and multi-stage pipelines /StormByte-Buffer
Config Human-readable text and versioned binary documents (groups, lists, raw bytes) /StormByte-Config
Crypto Hash, compression, encryption, signatures and key agreement; Crypto++ remains private /StormByte-Crypto
Database One SQL API over SQLite, PostgreSQL, MariaDB and MSSQL /StormByte-Database
Logger Stream logging with levels, headers, components, ThreadedLog and Scope /StormByte-Logger
Multimedia Decode, filter, encode and mux media through FFmpeg; public APIs abstract FFmpeg types /StormByte-Multimedia
Network Framed packets, client/server endpoints, IPv4/IPv6 TCP, Crypto TLS and authorized remote-file channels /StormByte-Network
System Processes, pipes, devices, host information and environment variables /StormByte-System

Public API

Under StormByte::Network:

Type Role
Client / Client::Error Inherit; typed total-budget Connect/Send, thread-safe cancellation; optional TLS
Server Inherit; implement ProcessClientPacket
Transport::Packet Inherit; implement DoSerialize
Connection::Protocol IPv4 / IPv6
Connection::Status Lifecycle
Exception / ConnectionError / ConnectionClosed Errors
Telemetry / ClientTelemetry / ServerTelemetry Base-clock measurements and retained per-client / aggregate-server snapshots
RemoteFileMount Public, versioned descriptor/result for an application-authorized file mount
BufferedRemoteFileReader / BufferedRemoteFileWriter Buffer file-like handles over private channels
HTTP::Client / HTTP::Request / HTTP::Response Bounded HTTP/1.1 and HTTP/2 requests over plain HTTP or authenticated HTTPS
HTTP::Header / HTTP::Options / HTTP::Error Duplicate-preserving fields, explicit limits/deadline/cancellation and typed failures

Sockets, frames and Winsock bootstrap are private.

Public polymorphic and callback types are MAYBE_SAFE: safe ownership does not make arbitrary derived state or captures safe across modules. Keep Base, Network, relevant dependencies and every provider module loaded with matching ABIs until all objects and callback copies are released. Allocate the exact derived packet type with PacketPointer::MakePointer<Derived>(), retain its virtual destruction path, and keep derived payload allocation/destruction in its provider module. Use StormByte::Safe::DynamicPointerCast or StormByte::Safe::StaticPointerCast for packet casts. Derived servers must call Disconnect() in their destructor body before handler state is destroyed. Safe string sizes count content bytes (or wide characters), excluding the null terminator.

Packet payloads use StormByte::Safe::Binary. Header-defined state, public and private, uses Safe containers, shared/unique ownership, synchronization, atomics and threads; standard borrowed views and scalars remain permitted. There is no ownership bridge through std::shared_ptr. StormByte::Size represents element counts and StormByte::ByteSize represents byte lengths and offsets, with explicit conversions at numeric and wire/OS boundaries. Do not interpret a container's element count as a byte length without accounting for its element type.

The exact STORMBYTE_DECLARE_MAYBE_SAFE macro registers complete public types and appropriate private types. It carries a provider lifecycle contract, not a blanket certification: fields and allocation paths must comply, each constructor, assignment and destructor must be implemented or explicitly deleted, and moved-from objects must remain valid for cleanup. A derived type needs its own review; the base declaration does not cover arbitrary derived storage. PIMPL is reserved for native OS resources (sockets, HANDLE, FILE*) or external-library state, not for hiding Safe values or owning STL state. See CODING_STYLE.md for the full contract.

Application request deadlines and cancellation

The synchronous application client now has additive, typed overloads:

auto connected = client.Connect(StormByte::Network::Connection::Protocol::IPv4,
"licensing.example", 443, std::chrono::seconds{5});
if (!connected && *connected.error() == StormByte::Network::Client::Error::TimedOut) {
// DNS wait, TCP connect and TLS authentication share the same five seconds.
}
// Inside a derived client: Send remains protected.
auto response = Send(packet, std::chrono::seconds{2});
if (!response && *response.error() == StormByte::Network::Client::Error::Cancelled) {
// Another thread called Cancel() or Disconnect().
}
@ TimedOut
The total operation budget expired.
Definition client.hxx:133
@ Cancelled
Cancel or Disconnect interrupted this operation.
Definition client.hxx:134
@ IPv4
IPv4 (AF_INET).
Definition protocol.hxx:61

Configure TLS and its expected server identity before connecting when the endpoint requires authentication; port 443 alone does not enable TLS. Connect(..., timeout) returns Expected<void, Client::Error> and Send(packet, timeout) returns Expected<PacketPointer, Client::Error>. Budgets use milliseconds: negative is InvalidTimeout, zero expires immediately, and milliseconds::max() explicitly opts out of expiry. Existing signatures remain available: the Boolean Connect uses a ten-second total budget, and the packet-handle Send keeps its legacy unlimited wait and empty-on-error result. Prefer the typed overloads for Internet-facing applications.

One absolute deadline includes operation queueing, DNS caller waiting and every connect alternative, TLS handshake, the complete upload, opcode, size, payload, pipeline transformations and deserialization. Partial plaintext or TLS progress never restarts it. Typed failures distinguish expiry, cancellation, resolver busy, native transport/EOF, TLS authentication, invalid packet/policy, allocation and connection preconditions. A failed operation that consumed stream bytes discards the connection rather than retrying or replaying a partial frame. Invalid arguments or expiry before acquiring/using a stream do not destroy it.

Cancel() is thread-safe against connect/request I/O and status queries: it sets a sticky flag and calls native shutdown on an established socket, waking blocked I/O without concurrently closing or reusing its handle. POSIX poll reports that local shutdown immediately; Winsock select does not, so Windows waits observe the flag at their next bounded wait slice of at most 50 ms. It also invalidates an idle application connection. Disconnect() performs the same cancellation and immediately releases an idle connection; an active request or connect releases its own stream on return. A subsequent Connect clears the cancelled state and can reconnect. Remote-file planes keep their existing, independent lifecycle and are not cancelled by these application-stream calls.

Requests/connects serialize internally, but queued calls retain their original deadline and can expire without waiting for the active request. Only Cancel, Disconnect, Status and Telemetry may be called reentrantly from packet callbacks. Moves, destruction and caller-owned callback state still need external lifetime synchronization; do not destroy a client while any call is running. Callbacks and pipeline work are synchronous and cannot be preempted: expiry/cancellation is reported on their return. Scheduler delays, allocation and native setup are not hard real-time guarantees.

Each client retains one managed DNS slot. An OS getaddrinfo already running cannot be cancelled: timeout/cancellation stops caller waiting, not the lookup. The slot reports ResolverBusy until it finishes, and client/resolver destruction joins outstanding DNS work, potentially beyond the operation budget.

If a derived class overrides the legacy Connect, C++ name hiding also applies to the new overload: expose it with using StormByte::Network::Client::Connect, or provide a timed wrapper that also performs your application's login flow.

Loopback latency is regression-tested over 128 plaintext and 128 TLS pings. The previously reported approximately one-second round trip was not reproduced in the pre-change baseline (plaintext 115–878 µs, TLS 27–207 µs, five each), so no polling-interval root cause or speculative latency fix is claimed.

HTTP and HTTPS client

StormByte::Network::HTTP::Request request("https://example.com/data?q=1");
request.headers.emplace_back("Accept", "application/octet-stream");
options.timeout = std::chrono::seconds{10};
options.body_bytes = StormByte::ByteSize{1024 * 1024};
auto response = client.Execute(request, options);
if (response) {
// response->status, headers, trailers and Safe::Binary body
}
else {
// *response.error() is HTTP::Error; no request was retried.
}
Synchronous single-request-per-connection client.
Definition client.hxx:399
Expected< Response, Error > Execute(const Request &request, const Options &options={})
Execute one bounded request, closing its connection on all exits.
Scalar request limits.
Definition client.hxx:340
std::chrono::milliseconds timeout
One total DNS-to-body deadline.
Definition client.hxx:378
ByteSize body_bytes
Maximum buffered or streamed body in either direction.
Definition client.hxx:383
Fully buffered request.
Definition client.hxx:192

Use request.method = std::string_view{"POST"} and assign request.body a Safe::Binary for binary uploads, including embedded NULs. Ordered header occurrences preserve duplicates in both directions. Response field names are normalized to lowercase. Options separately bounds URL bytes, aggregate headers/field count (including interim responses and trailers), buffered bodies in either direction, incoming HTTP wire bytes, and interim-response count. HTTP/2 decoded header accounting includes the RFC per-field 32-byte overhead. http2_bytes additionally caps live nghttp2 session allocations, including HPACK literal storage allocated before decoded-header callbacks are invoked. Cancellation borrows a const Safe::Atomic<bool>* until Execute returns. One positive timeout (at most 24 hours) covers DNS waiting, connect alternatives, TLS authentication, upload and the complete response; it never restarts between chunks or protocol phases.

Protocol::Automatic uses HTTP/1.1 on cleartext and offers h2, then http/1.1, over HTTPS. Authenticated HTTPS peers without ALPN use HTTP/1.1, as specified for legacy HTTP endpoints. Protocol::HTTP1 offers only HTTP/1.1; Protocol::HTTP2 requires h2 over HTTPS or sends an explicit HTTP/2 prior- knowledge preface on cleartext. There is no probing, replay, fallback after failure, or HTTPS-to-HTTP downgrade. nghttp2 supplies real HTTP/2 framing, HPACK, SETTINGS and flow control; neither it nor OpenSSL appears in this API.

The HTTP/1 parser accepts HTTP/1.0 responses, fixed lengths, chunked framing and close-delimited bodies, consumes bounded informational responses, and handles HEAD/204/304 bodylessness. It rejects ambiguous/conflicting framing, malformed chunks and headers, forbidden trailers, truncated bodies and unnotified TLS EOF. Only chunked transfer coding is supported; other transfer codings fail explicitly. HTTP/2 supports a single locally initiated request stream with bounded buffered upload/download, trailers, resets and GOAWAY validation; server push is disabled.

Default HTTPS uses Crypto's bundled server roots and the URL's DNS or binary IP identity, validating at each new session's current time. ConfigureTLS deeply copies a Crypto::TLS::ClientConfiguration for exclusive custom CAs, an explicit expected identity, revocation evidence, TLS policy and optional mTLS chain/key/password. The configured identity overrides URL-derived identity; ALPN remains controlled by HTTP options. Configuration failure preserves the previous policy. The default refresh_validation_time=true must normally be retained; false deliberately opts into a supplied fixed validation instant for offline tests/evidence. Crypto currently supports TLS 1.3 only.

Each request opens and closes a fresh connection. There is no connection pool, parallel multiplexing, redirect following (3xx is returned unchanged), automatic content decompression, proxy, CONNECT/Upgrade/Expect, HTTP server, or HTTP/3/ QUIC. Host, connection, framing and related hop-by-hop request headers are client-managed and rejected if supplied by the application. No failed request is replayed. A request can fail after the peer already received some/all of its bytes; do not blindly retry non-idempotent operations.

Serialize each client's execution/configuration/moves/destruction. A timed-out DNS call leaves at most one managed worker until the OS lookup finishes; subsequent calls can report ResolverBusy. Destruction joins retained DNS work and may wait beyond the request deadline. Request/response/header owning fields are Safe values with out-of-line Network lifecycle; copies have independent value semantics, moved owning fields are empty, and moved clients must be reassigned before reuse. Keep Network, Crypto, Base and other providers loaded with compatible ABIs until all objects/results are destroyed.

Network telemetry

Client::Telemetry() returns StormByte::Safe::Shared<ClientTelemetry> for that client instance. It records connection attempts/results and application Send request/response/no-response counts with mean round-trip latency. A no-response result is not necessarily a transport failure: applications may intentionally use one-way commands. Server::Telemetry() returns StormByte::Safe::Shared<ServerTelemetry> aggregated across all application sessions handled by that server. It records current, accepted, closed and peak connections; packets dispatched; handlers completed, empty and errored; mean handler duration; and worker-queue backpressure events. Counters are cumulative for the telemetry object's lifetime; connection count is a live gauge.

Keep either shared handle to retain its last snapshot after the owning Client or Server is destroyed. Timed operations use independent, stable StormByte::Clock::Sample values sharing named clocks from StormByte::Telemetry; nested or concurrent measurements do not depend on thread-local nesting depth, and a sample can move between threads. Repeated Stop() calls do not record it again. Remote-file byte/read/write statistics remain on Buffer's existing per-handle telemetry and are not folded into the application-protocol counters.

TLS and application admission

Inherited Client and Server expose ConfigureTLS publicly. Before connecting, pass a StormByte::Crypto::TLS::ClientConfiguration to the client and a ServerConfiguration to the server. Network validates and deeply copies all borrowed inputs, including identity, custom roots, certificate/key/password bytes, ALPN, revocation evidence and policy lists. Caller buffers may be released immediately. Client authentication requires an explicit DNS or binary IP SAN identity; custom roots are exclusive, not merged with the bundled trust store. Server configuration may require client certificates with exclusive custom client roots for mTLS. Crypto provides TLS 1.3; Network neither exposes nor directly calls OpenSSL.

Configuration is permitted only while disconnected; clients also reject changes while their remote-file plane remains attached. Invalid configuration leaves the previous snapshot intact. DisableTLS() explicitly restores plaintext while stopped. Unconfigured peers retain plaintext behavior; configured peers require TLS and never retry as plaintext. Snapshots persist across reconnects and moves, but every TCP connection creates an independent TLS session. Serialize configuration, connect, moves and destruction externally; keep Network, Crypto, Base and callback providers loaded until their owners are released.

ConfigureTLS(configuration, refresh_validation_time = true) uses current system time, rounded to seconds, for every newly constructed primary or auxiliary TLS session, including reconnects. Retained policy never freezes production certificate validation at configuration time. Explicitly pass false to preserve Crypto's supplied validation_time for deterministic offline tests or intentionally fixed-time revocation-evidence validation; this opt-in also remains fixed across reconnects. Refresh applies to client server-certificate validation and server mTLS client-certificate validation.

Protected AllowIncomingOpcode(uuid, opcode) and AllowOutgoingOpcode(uuid, opcode) accept all opcodes by default. Application authorization, login and ACLs remain the derived application's responsibility and are separate from TLS authentication. Incoming checks run before the packet factory; outgoing checks run before encoding. Server hooks run on the event loop and must synchronize state shared with worker handlers without blocking on network exchanges. For TLS peers, OnClientConnected(uuid) runs only after successful authenticated handshake, never on TCP acceptance, and no packets reach factories or handlers earlier. OnClientDisconnected(uuid) cleans up admitted sessions only. Pending primary handshakes are limited to 64 with a ten-second deadline; the server advances bounded nonblocking reads/writes rather than waiting for one peer.

Frames following an application login remain unprocessed while its handler is active, even when multiple messages arrived in the same TCP read. Only after the previous handler completes are the next opcode's policy and factory evaluated using the updated state. Unknown opcodes, invalid payloads and factory exceptions fail closed.

TLS protects the complete wire stream, including every opcode, serialized length and payload. Packet definitions, serialization, deserialization and handlers are unchanged. TLS record lengths and traffic timing remain observable. Bare TCP EOF without authenticated close-notify is a failure; explicit local disconnect remains abortive.

To return a rejection message before closing, a handler calls protected DisconnectClientAfterReply(uuid) and returns its application-defined rejection packet. Network discards pending input without executing its pipelines, factory or handlers, drains the response, then closes the socket. DisconnectClient(uuid) closes immediately without guaranteeing a reply. Draining completes local sends; it does not prove the remote application read them. Use an application ACK when that confirmation is required.

test/client_server_test.cxx exercises actual Crypto TLS with disposable offline identities and roots; test/remote_file_test.cxx covers protected file transfers. Offline fixtures explicitly opt into fixed-time validation inside certificate validity; dedicated regressions distinguish current-time defaults from invalid fixed instants. Its separate hardcoded login fixture demonstrates application authorization only, not production credential handling.

Breaking: protected ConfigurePipelines and ConfigureClientPipelines have been removed. Consumers using negotiated Buffer transforms (including Alchemist/Alchemy and other derived applications) must migrate to pre-connect TLS configuration and rebuild. Remove old configuration calls; do not replace them with plaintext negotiation of secrets.

Remote file channels

The derived server performs its normal application-opcode dispatch and ACL check first. After authorization it calls the protected MountRemoteFileReader or MountRemoteFileWriter helper and includes the returned RemoteFileMount in its application response. A denied ACL can instead return an application-defined Unauthorized packet. The client's packet factory decodes the public DTO, then its derived client calls CreateRemoteFileReader or CreateRemoteFileWriter.

RemoteFileReaderHandle and RemoteFileWriterHandle are StormByte::Safe::Unique owners of their concrete remote types. They can be moved into consumer functions accepting Safe::Unique<Buffer::IO::BufferedLocationReader> or Safe::Unique<Buffer::IO::BufferedLocationWriter> without moving or slicing the underlying object. Construction stays in Network; object storage is allocated and freed on Base's heap, and virtual destruction releases the remote mount. These handles do not convert to std::unique_ptr with its default deleter. This handle-type change requires consumers to rebuild.

RemoteFileMount::Status distinguishes Authorized, NotAuthorized, Unavailable (a missing read file), FileBeingRead, FileBeingWritten, and Failed. Rejected descriptors have Port() == 0, an empty capability token, and Access::None. The private channel has its own bounded opcode protocol and is not sent through the application's packet factory or ProcessClientPacket.

The first authorized mount for an application client session creates one private server listener and assigns its ephemeral port. Later mounts for that session reuse the same peer plane and port. The client connects lazily when it creates its first reader or writer. Each Authorized descriptor carries its own capability token and access mode, along with the plane's heartbeat timeout. The first authorized mount selects that timeout (3 to 3600 seconds; default 30), and later mounts on the same plane use it. A server allows at most 128 active mount capabilities across all client sessions.

The heartbeat timeout measures peer liveness, not disk-operation duration. Ping/Pong continues while a disk worker is occupied; a synchronous file call may remain pending beyond that interval while the peer keeps responding. Initial attachment remains time-bounded. File operations are serialized, with a heartbeat exchange allowed alongside them and one socket receiver correlating responses by request ID. Frames, pending work and response queues remain bounded and wire bytes never interleave. The receiver sleeps when no response is outstanding.

When the primary connection requires TLS, its auxiliary file plane requires TLS too, with the same immutable identity, trust, mTLS and policy snapshot and a new independent session. No channel falls back to plaintext. The server authenticates the auxiliary peer incrementally before parsing file frames or consulting tokens. TLS covers read/write contents, Attach/Open/CloseToken/Release, metadata, length prefixes and Ping/Pong heartbeats. Unconfigured primary connections retain plaintext file behavior. A pending file handshake expires after ten seconds or the selected plane silence timeout, whichever comes first.

Transport encryption is transparent to file contents. TLS encrypts client writes and server reads on the socket; the receiving endpoint authenticates and decrypts records before interpreting file messages. Host files contain the original bytes, not TLS ciphertext or framing. Buffered reads, writes, seeks, truncation and flushes therefore retain their normal behavior. Network does not provide encryption at rest. Canonical TLS tests compare remote binary reads and writes byte-for-byte, including embedded NUL and all byte values.

File protection follows primary TLS configuration automatically, so the application response carrying a capability is protected too. TLS server identity authentication does not replace application ACLs or capability ownership checks; enable mTLS when client certificate authentication is required. Unconfigured plaintext endpoints provide no confidentiality.

Each peer plane has one independently constructed TLS session when configured, plus one shared network-device snapshot. Only immutable configuration is shared with its primary connection; stream keys, transcript, record counters and buffers are never copied from another connection. Engine steps are serialized between file sends and the receiver without holding the engine lock during socket waits, preserving concurrent heartbeat responses during slow disk operations. File operations carry the mount token and an absolute byte offset, so reader handles keep independent cursors without wire-level seek requests.

Remote readers and writers retain Buffer's I/O telemetry, including its existing operation counters and rates. Buffer telemetry derives from StormByte::Telemetry and measures operations with Base's named clocks, so remote I/O uses the same instrumentation as other Buffer locations.

Transfer configuration (Buffer 4)

Remote handles inherit Configuration(), Configure(...), ReadChunk, WriteTransfer, WriteThreshold and Transfers() directly from Buffer; no Network-specific policy wrapper is required. Apply a complete policy after Open(), because opening a remote handle first probes the network window for the legacy automatic defaults. Check every operation's result:

namespace IO = StormByte::Buffer::IO;
// reader/writer are authorized, already-open remote handles.
auto read_policy = reader->Configuration();
read_policy.ReadChunk = ByteSize{256 * 1024};
read_policy.ReadAhead = ByteSize{1024 * 1024};
read_policy.MaxMemory = ByteSize{2 * 1024 * 1024};
const auto read_configuration = reader->Configure(read_policy);
if (read_configuration.status != IO::Status::Ok)
return false;
auto write_policy = writer->Configuration();
write_policy.WriteTransfer = ByteSize{256 * 1024};
write_policy.WriteThreshold = ByteSize{1024 * 1024};
write_policy.MaxMemory = ByteSize{2 * 1024 * 1024};
const auto write_configuration = writer->Configure(write_policy);
if (write_configuration.status != IO::Status::Ok)
return false;
const auto effective = writer->Transfers(); // No I/O.
// Check Flush()/Close() results before treating pending writes as completed.

ReadChunk limits each Buffer origin request (default/zero: 64 KiB), independently of ReadAhead (zero: no prefetch). WriteTransfer limits origin requests on every writing path (zero: no explicit maximum; page mode retains Buffer's 64 KiB fallback). A positive transfer setting in page mode is capped by the page budget. Each remote origin hook exchanges at most one file-data frame: the wire payload is additionally capped at 4 MiB minus its 58-byte header. Larger public operations and configured chunks complete through multiple segments; a short successful segment is not EOF. These are application transfer sizes, not physical disk-operation sizes.

WriteThreshold (default/zero: memory pressure only) is the dirty-page high watermark, capped by the page budget; draining targets half that watermark. Contiguous small writes can therefore become larger transfers. Page draining runs in the caller's thread, and Flush, Close and reconfiguration can materialize data below the watermark. WriteChunk and BackPressure retain their separate ring unit/queue-depth meaning; pages take priority when MaxMemory is nonzero. Defaults retain automatic network-window probing, the writer's 1 MiB page budget and depth four, and the reader's zero page budget. Ring admission retains Buffer's TryAgain behavior: a request larger than the current queue capacity must be split by the caller, not retried unchanged forever. Page-mode writes larger than their budget drain incrementally. The ring's allocated capacity is rounded to a power of two including a spare slot; RingCapacity and the logical QueueCapacity can therefore differ.

Configure serializes with Buffer operations, may block on in-flight I/O and flushes pending writer data before applying the new policy. A failed flush does not install a partial policy; already acknowledged remote writes cannot be rolled back. Setters can also block and throw on failed configuration. Transfers() reports actual origin-hook calls and bytes, effective transfer limits, page/ring/queue capacities and pending/in-flight payload, not wire/TLS overhead or consumer-delivered bytes. MaxRequest measures the request passed to the hook, before the additional protocol cap; it is a lifetime maximum, not the current configured limit.

MaxMemory accounts for Buffer page payload, not RSS or all transport memory. Ring storage, Buffer's assembly/replay and transfer scratch, the caller's buffers, protocol frame copies, TLS buffers and server-side stream buffering can require additional memory. Buffer's queue/ByteBudget APIs are not wired into the existing private data plane: it retains its own bounded exchange protocol. No aggregate file/transport memory cap, disk scheduler or physical read/write isolation is implied.

Breaking: remote handles inherit Buffer 4's changed base-class ABI. Update Buffer to 4.0.0, Crypto to 3.1.0, then Network and applications using these handles as one compatible set; do not mix Buffer 3 and Buffer 4 handle layouts or old virtual policy overrides. Provider-owned Safe handles and module-lifetime requirements are unchanged.

Remote reader size queries return StormByte::Safe::Optional<StormByte::ByteSize>: an empty value means the size is unavailable, not that the file is empty; a present zero means an empty file. Byte lengths and seek offsets use ByteSize; convert explicitly when an application needs a plain numeric value. A successful writer flush synchronizes buffered writes with the host stream; size queries must not disturb its write position. Flush is not a transactional commit or a guarantee of crash-durable storage.

The remote reader and writer expose the same shared polymorphic System::Device snapshot for their plane's local network interface. Its Throughput() and Window() report the interface link speed when the operating system exposes it, with a nominal network-rate fallback otherwise.

Readers of one canonical path share a mutex-protected host-side file handle; operations on it are serialized, while each reader keeps its own offset. A path may have multiple readers or one exclusive writer, but a writer mount is rejected while any reader or writer holds the path, and readers are rejected while a writer holds it. Mounting a writer does not truncate an existing file; a missing file is created, and Truncate() explicitly clears it. Close consumes that mount's token. The backing handle and path reservation are released when its final token closes; request a new mount to open another handle.

The data plane is owned by the Client object and survives Client::Disconnect() while that object remains alive, so already attached file handles can continue I/O without the application control connection. A subsequent successful Connect() replaces the old plane and invalidates its handles. Destroying the Client, a plane heartbeat timeout, or server shutdown also closes the plane and releases its tokens. The descriptor is a capability, not an authorization decision: every data operation revalidates the token and access. The private protocol bounds payloads and validates opcodes and sequence numbers. A failed plane marks every attached BufferedLocation* handle Fault so later I/O fails visibly.

Heartbeat failure during disk I/O revokes the plane's capabilities, stops new work and wakes failed client buffers. Results completed after revocation are discarded. A system call already in progress may finish and partially modify a file: its contents must then be treated as unreliable, with no rollback guarantee. Its worker retains the stream until the operation returns, allowing safe deferred release. Transport cancellation does not guarantee immediate interruption of that call or bounded shutdown time while the operating system keeps it blocked.

DeserializePacketFunction accepts copyable callables taking a packet opcode, Buffer::Consumer payload and Safe::Shared<Logger::Log>, and returning PacketPointer. Its target storage and clone/destroy trampolines belong to the provider that constructs it, so Network can retain and invoke the decoder without freeing callback memory through its own CRT. Copies own independently copied targets; reference/shared captures remain shared and must stay valid for every retained copy. Caller-sensitive construction uses STORMBYTE_FORCE_INLINE; conversions that create owning standard-library values must likewise execute in the caller's module. These rules also apply to Buffer pipe providers and require their modules to remain loaded.

Examples

A client

#include <utility>
class AppClient : public StormByte::Network::Client {
public:
: Client(std::move(fn), std::move(log)) {}
const StormByte::Network::Transport::Packet& packet) noexcept {
return Send(packet);
}
};
Forward declaration of the connected client implementation.
Abstract application client.
Definition client.hxx:124
PacketPointer Send(const Transport::Packet &packet) noexcept
Send packet and return the response (or nullptr).
Caller-owned callback that builds a packet from opcode and payload.
Definition typedefs.hxx:143
Polymorphic wire packet: opcode + payload hook.
Definition packet.hxx:73
StormByte::Safe::Shared< Transport::Packet > PacketPointer
Base-heap shared packet pointer.
Definition typedefs.hxx:132
STL namespace.

A server

#include <string_view>
class AppServer : public StormByte::Network::Server {
public:
using Server::Server;
~AppServer() noexcept override { Disconnect(); }
protected:
StormByte::Network::PacketPointer ProcessClientPacket(
std::string_view uuid,
StormByte::Network::PacketPointer packet) noexcept override {
(void)uuid;
return packet;
}
};
Abstract application server.
Definition server.hxx:148
void Disconnect() noexcept override
Stop accept, disconnect clients and close the listener.

Discovery

Network does not invent a discovery protocol. It only moves opaque bytes. A derived server decides whether a query matches and what to reply. A derived client decides what to send and which replies to accept.

Announce a server on a UDP port (independent of the TCP listen port):

class DiscoverableServer : public StormByte::Network::Server {
public:
using Server::Server;
~DiscoverableServer() noexcept override { StopAnnounce(); Disconnect(); }
bool Start(unsigned short tcp_port, unsigned short discovery_port) {
if (!Connect(Connection::Protocol::IPv4, "0.0.0.0", tcp_port))
return false;
m_tcp_port = tcp_port;
return Announce(Connection::Protocol::IPv4, discovery_port);
}
protected:
StormByte::Network::PacketPointer ProcessClientPacket(
std::string_view, StormByte::Network::PacketPointer) noexcept override {
return {};
}
// Query is opaque. Reply is opaque. Empty means "do not answer".
StormByte::Safe::Binary OnDiscoveryQuery(const StormByte::Safe::Binary& query) const noexcept override {
const std::string_view text(reinterpret_cast<const char*>(query.data()), query.size());
if (text != "FIND:my-service")
return {};
const std::string reply = "HERE:my-service:" + std::to_string(m_tcp_port);
return StormByte::Safe::Binary(reinterpret_cast<const std::byte*>(reply.data()), reply.size());
}
private:
unsigned short m_tcp_port = 0;
};
virtual StormByte::Safe::Binary OnDiscoveryQuery(const StormByte::Safe::Binary &query) const noexcept
Decide whether to answer a discovery query.
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.
bool Connect(const Connection::Protocol &protocol, std::string_view address, const unsigned short &port) override
Bind, listen and start the accept thread.

Discover from a client. on_reply returns true to stop, false to keep waiting until the timeout:

#include <iostream>
class DiscoveringClient : public StormByte::Network::Client {
public:
using Client::Client;
bool Find(unsigned short discovery_port) {
return Discover(Connection::Protocol::IPv4, discovery_port,
std::chrono::milliseconds(1500),
[this](const DiscoveryReply& reply) {
std::cout << "from " << std::string_view{reply.from_address}
<< ":" << reply.from_port
<< " payload " << reply.payload.size() << " bytes\n";
Safe::String address;
unsigned short tcp_port = 0;
if (!InterpretDiscoveryReply(reply.payload, address, tcp_port))
return false; // keep looking
std::cout << "accepted " << std::string_view{address} << ":" << tcp_port << "\n";
return true; // stop
});
}
protected:
StormByte::Safe::Binary MakeDiscoveryQuery() const noexcept override {
constexpr std::string_view q = "FIND:my-service";
return StormByte::Safe::Binary(reinterpret_cast<const std::byte*>(q.data()), q.size());
}
bool InterpretDiscoveryReply(const StormByte::Safe::Binary& reply,
StormByte::Safe::String& address,
unsigned short& port) const noexcept override {
const std::string_view text(reinterpret_cast<const char*>(reply.data()), reply.size());
constexpr std::string_view prefix = "HERE:my-service:";
if (!text.starts_with(prefix))
return false;
port = static_cast<unsigned short>(std::stoi(std::string(text.substr(prefix.size()))));
address = "127.0.0.1"; // or use the source address from DiscoveryReply in the callback
return true;
}
};
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.
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.
virtual StormByte::Safe::Binary MakeDiscoveryQuery() const noexcept
Build the opaque discovery query.

IPv6 uses the same calls with Connection::Protocol::IPv6. Network sends to the link-local multicast group instead of the IPv4 broadcast address. The derived code does not change.

A packet

class PingPacket : public StormByte::Network::Transport::Packet {
public:
PingPacket() : Packet(1) {}
protected:
StormByte::Safe::Binary DoSerialize() const noexcept override {
return {};
}
};
}
virtual StormByte::Safe::Binary DoSerialize() const noexcept=0
Payload-only serialization (no opcode).
static Shared< T > MakePointer(Args &&... args)

Design notes

  • Application request/response calls on one connection are not a thread-safe multiplex. The private remote-file plane separately multiplexes heartbeat with serialized file operations. The server keeps socket I/O in its event loop and dispatches packet handlers through a bounded internal pool.
  • Client request/response APIs remain synchronous to the caller; a slow packet handler no longer blocks socket I/O for unrelated clients.
  • A slow peer is isolated by per-session output limits; once a session exceeds its output budget, the server closes that session rather than allowing unbounded memory growth.
  • Connect on Server means bind + listen + accept loop.
  • Frame layout uses host size_t for payload length. Same architecture on both ends.
  • Configured TLS protects all application and file-protocol bytes, regardless of opcode threshold.

Testing

Package discovery fixtures are CI-only and require -DENABLE_CI_FIXTURES=ON, which is disabled by default and enabled explicitly by CI. Normal API tests, including network service discovery and TLS fixtures, remain available locally and during PGO training with -DENABLE_TEST=ON.

Enable tests with -DENABLE_TEST=ON and run CTest from the build's test/ registration root. For development validation, use a temporary build directory and leave the user's build/ untouched unless explicitly authorized:

cmake -S . -B build-validation -DENABLE_TEST=ON -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
cmake --build build-validation -j
ctest --test-dir build-validation/test --output-on-failure

The Network 3.1.0 client-control validation evidence and reproduction scripts include ordinary and sanitizer test logs, baseline/final loopback timings and the exact compiler-ABI investigation. Linux release archives use Clang; GCC and Clang currently mangle some constrained Base templates differently, even when both use libstdc++. Match the provider's compiler ABI for binary validation, or use a compatible source-built provider. Optimized inlining can mask that mismatch and is not proof of general binary compatibility.

The registered suites cover client/server exchanges, negotiated handshakes and remote-file behavior. Fourteen public Safe suites cover Client, ClientTelemetry, ConnectionClosed, ConnectionError, DeserializePacketFunction, Endpoint, Exception, FrameError, Packet, PacketError, RemoteFileMount, Server, ServerTelemetry and Telemetry. Integration regressions exercise exact-derived destruction, callback copies, endpoint lifecycle and remote writer write/size/flush byte integrity. No private-class suites are registered. Coverage in the source tree is not a claim that every platform or configuration passes. Linux tests and sanitizers do not prove separate Windows CRT heap safety; that requires provider/consumer module validation on Windows with compatible ABIs and explicit module-lifetime checks.

HTTPTest exercises the public HTTP client across the shared-library boundary using ephemeral loopback HTTP/1, Crypto TLS HTTP/1/h2, and cleartext nghttp2 fixtures. It covers binary uploads/downloads (including HTTP/2 responses beyond the initial flow-control window), duplicate fields/trailers, framing failures, limits, cancellation/deadlines, ALPN, exclusive trust, identity validation and mutual authentication. Offline keys under test/fixtures/tls are deliberately disposable test data, not production credentials. Their CA signing keys were destroyed. Most trust tests opt into fixed time; a separate test intentionally checks current-time validation and therefore requires a clock within the server fixture's validity period (2026-10-01 through 2027-10-01 UTC). Regenerate and re-sign the fixtures before that period ends to keep current-time tests valid. The mTLS client has a separate client-authentication EKU and disposable client CA.

Contributing

Issues on GitHub. No wiki, no discussions.

License

StormByte-Network original source is dual-licensed under the GNU Lesser General Public License v3.0 or later, or a commercial license from the copyright holder (David C. Manuelda, StormBytePP).

See [LICENSE](LICENSE), COPYING.LGPLv3, [THIRD-PARTY](THIRD-PARTY), and https://www.gnu.org/licenses/lgpl-3.0.html. The binary archive links Base, Buffer, Logger and System at run time; each keeps its own license. Neither license grants patent rights.