Socket Library

Maturity Notice: This library is functional and well-tested but newly released. It is appropriate for development, internal tooling, and controlled environments. Production deployment with untrusted network input should wait until the codebase has accumulated several months of real-world hardening.

High-performance, exception-driven socket toolkit for POSIX systems. Provides a clean, modern C API for TCP, UDP, Unix domain sockets, HTTP/1.1, HTTP/2, QUIC, WebSocket, and TLS/DTLS with comprehensive error handling, zero-copy I/O, and cross-platform event polling.

Features

Core Networking

• TCP Stream Sockets - Full-featured TCP client/server with scatter/gather I/O
• UDP Datagram Sockets - Connectionless and connected modes with multicast/broadcast
• Unix Domain Sockets - IPC sockets with peer credential support and file descriptor passing
• TLS 1.3 Support - Modern TLS with SNI, ALPN, session resumption, CRL/OCSP, certificate pinning, Certificate Transparency (CT), kTLS offload, 0-RTT early data, KeyUpdate
• DTLS 1.2+ Support - Secure UDP with cookie exchange for DoS protection, session caching, ALPN

HTTP Protocol Stack

• HTTP/1.1 - Table-driven DFA parser (RFC 9112), chunked encoding, request smuggling prevention
• HTTP/2 - Binary framing, stream multiplexing, flow control, server push (RFC 9113)
• HPACK - Header compression with static/dynamic tables, Huffman coding (RFC 7541)
• QPACK - HTTP/3 header compression (RFC 9204), two-stream architecture, blocked stream management
• HTTP Client - Connection pooling, authentication (Basic/Digest/Bearer), cookies (RFC 6265)
• HTTP Server - Event-driven request handling, keep-alive, graceful shutdown

QUIC Transport

• RFC 9000 Compliant - Full QUIC v1 transport protocol implementation
• Connection Management - Connection ID rotation, stateless reset, address validation
• Stream Multiplexing - Bidirectional and unidirectional streams with flow control
• Loss Detection - RFC 9002 congestion control and loss recovery
• Path Migration - Seamless connection migration across network changes
• 0-RTT Resumption - Fast reconnection with early data support

QUIC-TLS (RFC 9001)

• Packet Protection - AEAD encryption (AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305)
• Header Protection - AES-ECB/ChaCha20 mask generation for packet number encryption
• Key Derivation - HKDF-based initial secrets from client DCID, handshake/traffic keys
• Key Update - Key phase bit rotation with AEAD confidentiality limits (RFC 9001 §6)
• Retry Integrity - AEAD tag verification for Retry packets (RFC 9001 §5.8)
• Transport Parameters - TLS extension (type 0x39) for QUIC configuration exchange

QPACK (RFC 9204)

• Header Compression - HTTP/3 header compression avoiding head-of-line blocking
• Two-Stream Architecture - Separate encoder (0x02) and decoder (0x03) streams
• Dynamic Table - Absolute indexing with encoder-relative and field-relative schemes
• Static Table - 99 pre-defined entries (RFC 9204 Appendix A)
• State Synchronization - Section Acknowledgment, Stream Cancellation, Insert Count Increment
• Blocked Stream Management - Configurable blocked stream limits with SETTINGS negotiation

WebSocket

• RFC 6455 Compliant - Full WebSocket protocol implementation
• permessage-deflate - Compression extension (RFC 7692) via zlib
• Incremental UTF-8 - DFA-based text frame validation
• Auto-Ping/Pong - Configurable heartbeat with timer integration

Proxy Tunneling

• HTTP CONNECT - Proxy tunneling with Basic authentication
• SOCKS4/4a - Legacy SOCKS support
• SOCKS5 - RFC 1928/1929 with username/password authentication
• Async API - Non-blocking proxy connection with state machine

Event System

• Cross-Platform Polling - epoll (Linux), kqueue (BSD/macOS), poll fallback
• Edge-Triggered Mode - High-performance event notification
• Async I/O - io_uring (Linux 5.1+), kqueue AIO (BSD/macOS)
• Timers - One-shot and repeating with O(log n) min-heap

Connection Management

• Connection Pooling - O(1) lookup with hash tables, per-connection I/O buffers
• Happy Eyeballs - RFC 8305 dual-stack IPv4/IPv6 connection racing
• Auto-Reconnection - Exponential backoff with circuit breaker pattern
• Graceful Shutdown - Pool drain state machine with timeout guarantee

Security Hardening

• SYN Flood Protection - Reputation scoring, throttling, kernel integration
• Per-IP Tracking - Connection limits and rate limiting per client
• Rate Limiting - Token bucket algorithm for connections and bandwidth
• Request Smuggling Prevention - Strict HTTP parsing with RFC compliance

DNS Resolution

• Async Resolver - Non-blocking resolution with thread pool and query multiplexing
• DNS-over-TLS (DoT) - RFC 7858/8310 encrypted DNS with opportunistic/strict modes
• DNS-over-HTTPS (DoH) - RFC 8484 DNS queries over HTTPS (POST/GET methods)
• DNSSEC Validation - RFC 4033-4035 chain of trust, NSEC/NSEC3 authenticated denial
• DNS Cookies - RFC 7873 spoofing protection via EDNS0
• Negative Caching - RFC 2308 proper NXDOMAIN/NODATA handling
• Extended DNS Errors - RFC 8914 detailed error codes

Infrastructure

• Exception-Based Errors - Clean error propagation with TRY/EXCEPT/FINALLY
• Simple API - Return-code based convenience layer for common operations (no TRY/EXCEPT needed)
• Arena Memory Management - Efficient allocation with overflow protection
• Circular Buffer I/O - Zero-copy buffering for network operations
• Asynchronous I/O - Platform-optimized async operations (io_uring/kqueue)
• UTF-8 Validation - Security-focused UTF-8 processing for WebSocket text frames
• Generic Retry Framework - Exponential backoff with jitter for resilient operations
• Per-IP Connection Tracking - Connection limits and rate limiting per client IP
• Zero-Copy I/O - Platform-optimized sendfile() and scatter/gather I/O
• Observability - Pluggable logging, Prometheus/StatsD/JSON metrics export, event dispatching
• Cryptographic Utilities - SHA-1/256, HMAC, Base64, secure random

Platform Requirements

• POSIX-compliant system (Linux, BSD, macOS)
• C11 compiler with GNU extensions
• POSIX threads (pthread) for thread-safe operations
• IPv6 support in kernel (for dual-stack sockets)
• NOT portable to Windows without Winsock adaptation layer

Platform-Specific Features

Feature	Linux	BSD/macOS	Fallback
Event polling	epoll	kqueue	poll(2)
Async I/O	io_uring (5.1+)	kqueue AIO	edge-triggered
TCP Fast Open	3.7+	10.0+/10.11+	disabled
Congestion control	configurable	-	-
Peer credentials	SO_PEERCRED	LOCAL_PEERCRED	-
SYN protection	TCP_DEFER_ACCEPT	SO_ACCEPTFILTER	userspace

TLS/DTLS Requirements

• OpenSSL 1.1.1+ or LibreSSL with TLS 1.3 support
• TLS 1.3-only by default (configurable)
• DTLS 1.2 minimum for secure UDP

Quick Start

Building

# Basic build
cmake -S . -B build
cmake --build build -j

# Run tests
cd build && ctest --output-on-failure

# Build with TLS support (auto-detects OpenSSL/LibreSSL)
cmake -S . -B build -DENABLE_TLS=ON