Crafter.Network/README.md

Crafter.Network

A cross-platform C++ networking library providing TCP, QUIC, and HTTP/3 client/server functionality with modern C++ features.

Overview

Crafter.Network is a C++ networking library designed for modern C++ applications. It provides TCP, QUIC, and HTTP/3 networking capabilities with support for synchronous and asynchronous operations, making it suitable for a wide range of networking tasks including real-time multiplayer games.

Features

• TCP Networking: Client and server implementations for raw TCP connections.
• QUIC Networking: Encrypted, multi-stream transport via msquic — reliable streams for control plane, unreliable datagrams for low-latency state sync.
• HTTP/3: Client and server implementations on top of QUIC. Uses ALPN h3, QUIC bidi streams for requests/responses, the mandatory unidirectional control stream + SETTINGS frame (RFC 9114 §6.2.1), and a built-in QPACK codec (RFC 9204) with the full static table, Huffman decoding (RFC 7541), and literal-only emission. The QPACK dynamic table is unused; the optional QPACK encoder/decoder unidi streams are deliberately not opened (RFC 9204 §4.2 permits this when no dynamic-table operations are issued). The client is interoperable with mainstream public h3 endpoints (cloudflare, nghttp3-based servers, etc.).
• Asynchronous Operations: Thread pool–based async operations for improved performance.
• Cross-Platform: Built for Unix-like systems with socket-based networking.
• Modern C++: Uses C++20 modules, STL containers, and modern C++ features.

Architecture

The library follows a modular design using C++20 modules:

Core Modules

• Crafter.Network: Main module that exports all components
• Crafter.Network:ClientTCP: TCP client implementation
• Crafter.Network:ListenerTCP: TCP server implementation
• Crafter.Network:ClientHTTP: HTTP/3 client (ALPN h3)
• Crafter.Network:ListenerHTTP: HTTP/3 server (ALPN h3)
• Crafter.Network:HTTP: HTTP request/response types and constructors
• Crafter.Network:ClientQUIC: QUIC connection (client + accepted-server side) with reliable streams and unreliable datagrams
• Crafter.Network:ListenerQUIC: QUIC listener accepting incoming connections

The Crafter.Network:HTTP3 partition contains internal HTTP/3 wire-format helpers (QUIC varint, frame layer, QPACK static-table codec) and is intentionally not re-exported from the main module — it is shared between the ClientHTTP and ListenerHTTP implementations.

Components

TCP Components

ClientTCP

// Create a TCP client
Crafter::ClientTCP client("localhost", 8080);
client.Send("Hello World", 11);

// Receive data
std::vector<char> data = client.RecieveSync();

ListenerTCP

// Create a TCP listener
auto callback = [](Crafter::ClientTCP* client) {
    // Handle new connection
};
Crafter::ListenerTCP listener(8080, callback);
listener.ListenSyncSync(); // Synchronous listening

HTTP/3 Components

HTTP/3 runs over QUIC, which always requires TLS. Pass server credentials when constructing the listener (or set selfSigned = true for a development-only ephemeral cert) and matching client credentials when constructing the client (insecureNoServerValidation = true for self-signed servers).

ClientHTTP

Crafter::QUICClientCredentials creds;
creds.insecureNoServerValidation = true; // dev-only
Crafter::ClientHTTP client("localhost", 8082, creds);

Crafter::HTTPResponse response = client.Send(
    Crafter::CreateRequestHTTP("GET", "/", "localhost")
);
// response.status is the numeric status as a string, e.g. "200"

ListenerHTTP

std::unordered_map<std::string,
    std::function<Crafter::HTTPResponse(const Crafter::HTTPRequest&)>> routes;
routes["/hello"] = [](const Crafter::HTTPRequest&) {
    return Crafter::CreateResponseHTTP("200", "Hello World!");
};

Crafter::QUICServerCredentials creds;
creds.selfSigned = true; // dev-only
Crafter::ListenerHTTP listener(8082, creds, routes);
listener.Listen();

The HTTPRequest exposes the four HTTP/3 pseudo-headers (method, scheme, authority, path) as named struct fields rather than mixing them into the regular headers map. Routes are dispatched by exact match on path; unmatched paths return a synthetic 404.

Build Configuration

The project uses a configuration system with multiple build targets:

• base: Core interfaces only
• lib: Static library build with dependencies
• lib-debug: Debug static library build
• lib-shared: Shared library build with dependencies

Testing

The library includes tests covering:

• HTTP/3 round-trip (ShouldSendRecieveHTTP) — canonical local client/server round-trip
• HTTP/3 connection multiplexing (ShouldSendRecieveKeepaliveHTTP) — two requests share one QUIC connection
• HTTP/3 large body transfer (ShouldSendRecieveLargeHTTP) — 10 MiB POST
• HTTP/3 external interop (ShouldSend) — live fetch from cloudflare-quic.com:443, exercises real TLS chain validation, mandatory control stream, peer-initiated unidi streams, and QPACK Huffman decoding
• QUIC reliable streams
• QUIC unreliable datagrams

The external-interop test requires outbound UDP/443; if your network blocks it the test will fail.

Dependencies

• Crafter.Thread: Thread pool management for asynchronous operations.
• msquic — fetched and built automatically as a Crafter ExternalDependency (no system install required). The build clones microsoft/msquic recursively into the per-project external cache, configures it via CMake (QUIC_TLS_LIB=quictls, tests/tools/perf disabled), and links the produced libmsquic into the QUIC and HTTP/3 modules.
  • On Linux msquic links against libnuma (provided by the numactl package on most distros).
• The self-signed-cert path used by tests/dev shells out to the openssl CLI; install openssl if you intend to use QUICServerCredentials{selfSigned = true}.

Usage Example

#include <Crafter.Network>
#include <iostream>

int main() {
    Crafter::QUICClientCredentials creds;
    creds.insecureNoServerValidation = true;
    Crafter::ClientHTTP client("localhost", 8443, creds);

    auto response = client.Send(Crafter::CreateRequestHTTP("GET", "/", "localhost"));

    std::cout << "Status: " << response.status << std::endl;
    std::cout << "Body: " << response.body << std::endl;
    return 0;
}

License

This library is licensed under the GNU Lesser General Public License version 3.0. See LICENSE for more information.

Copyright

Copyright (C) 2026 Catcrafts® Catcrafts.net