144 lines
6.5 KiB
Markdown
144 lines
6.5 KiB
Markdown
# 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
|
||
```cpp
|
||
// Create a TCP client
|
||
Crafter::ClientTCP client("localhost", 8080);
|
||
client.Send("Hello World", 11);
|
||
|
||
// Receive data
|
||
std::vector<char> data = client.RecieveSync();
|
||
```
|
||
|
||
#### ListenerTCP
|
||
```cpp
|
||
// 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
|
||
```cpp
|
||
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
|
||
```cpp
|
||
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
|
||
|
||
```cpp
|
||
#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](LICENSE) for more information.
|
||
|
||
## Copyright
|
||
|
||
Copyright (C) 2026 Catcrafts®
|
||
Catcrafts.net
|