full QUIC support
This commit is contained in:
parent
45479a46ff
commit
28fab2509b
18 changed files with 1334 additions and 645 deletions
90
README.md
90
README.md
|
|
@ -1,19 +1,19 @@
|
|||
# Crafter.Network
|
||||
|
||||
A cross-platform C++ networking library providing TCP and HTTP client/server functionality with modern C++ features.
|
||||
A cross-platform C++ networking library providing TCP, QUIC, and HTTP/3 client/server functionality with modern C++ features.
|
||||
|
||||
## Overview
|
||||
|
||||
Crafter.Network is a comprehensive networking library designed for modern C++ applications. It provides TCP, HTTP, and QUIC networking capabilities with support for synchronous and asynchronous operations, making it suitable for a wide range of networking tasks including real-time multiplayer games.
|
||||
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 TCP connections
|
||||
- **HTTP Support**: Full HTTP client and server implementations with routing capabilities
|
||||
- **QUIC Networking**: Encrypted, multi-stream transport via msquic — reliable streams for control plane, unreliable datagrams for low-latency state sync
|
||||
- **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++ modules, STL containers, and modern C++ 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
|
||||
|
||||
|
|
@ -23,12 +23,14 @@ The library follows a modular design using C++20 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 client implementation
|
||||
- `Crafter.Network:ListenerHTTP`: HTTP server implementation
|
||||
- `Crafter.Network:HTTP`: HTTP protocol utilities and data structures
|
||||
- `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
|
||||
|
|
@ -53,30 +55,38 @@ Crafter::ListenerTCP listener(8080, callback);
|
|||
listener.ListenSyncSync(); // Synchronous listening
|
||||
```
|
||||
|
||||
### HTTP Components
|
||||
### 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
|
||||
// Create an HTTP client
|
||||
Crafter::ClientHTTP client("httpbin.org", 80);
|
||||
Crafter::QUICClientCredentials creds;
|
||||
creds.insecureNoServerValidation = true; // dev-only
|
||||
Crafter::ClientHTTP client("localhost", 8082, creds);
|
||||
|
||||
// Send HTTP request
|
||||
std::string request = Crafter::CreateRequestHTTP("GET", "/get", "httpbin.org");
|
||||
Crafter::HTTPResponse response = client.Send(request);
|
||||
Crafter::HTTPResponse response = client.Send(
|
||||
Crafter::CreateRequestHTTP("GET", "/", "localhost")
|
||||
);
|
||||
// response.status is the numeric status as a string, e.g. "200"
|
||||
```
|
||||
|
||||
#### ListenerHTTP
|
||||
```cpp
|
||||
// Create an HTTP listener with routes
|
||||
std::unordered_map<std::string, std::function<std::string(const Crafter::HTTPRequest&)>> routes;
|
||||
routes["/hello"] = [](const Crafter::HTTPRequest& req) {
|
||||
return Crafter::CreateResponseHTTP("200 OK", "Hello World!");
|
||||
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::ListenerHTTP listener(8080, routes);
|
||||
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:
|
||||
|
|
@ -88,19 +98,22 @@ The project uses a configuration system with multiple build targets:
|
|||
|
||||
## Testing
|
||||
|
||||
The library includes comprehensive tests covering:
|
||||
- Compilation verification
|
||||
- HTTP receive functionality
|
||||
- HTTP send functionality
|
||||
- HTTP send/receive operations
|
||||
- Keep-alive HTTP operations
|
||||
- Large HTTP data transfers
|
||||
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 modules.
|
||||
- **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
|
||||
|
||||
|
|
@ -109,15 +122,14 @@ The library includes comprehensive tests covering:
|
|||
#include <iostream>
|
||||
|
||||
int main() {
|
||||
// Simple HTTP client example
|
||||
Crafter::ClientHTTP client("httpbin.org", 80);
|
||||
|
||||
auto request = Crafter::CreateRequestHTTP("GET", "/get", "httpbin.org");
|
||||
auto response = client.Send(request);
|
||||
|
||||
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;
|
||||
}
|
||||
```
|
||||
|
|
@ -129,4 +141,4 @@ This library is licensed under the GNU Lesser General Public License version 3.0
|
|||
## Copyright
|
||||
|
||||
Copyright (C) 2026 Catcrafts®
|
||||
Catcrafts.net
|
||||
Catcrafts.net
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue