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
```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