Introduction to UVHTTP

UVHTTP is an event-driven HTTP/1.1 and WebSocket server library for C, built on libuv. These docs cover building web services with it.

🎯 What is UVHTTP?

UVHTTP is an event-driven HTTP server library for C, built on libuv:

Throughput: peak 23,226 RPS, sub-millisecond latency
Resource use: small memory footprint and CPU usage via zero-copy
Architecture: 64-bit and 32-bit embedded support
API: clean, with error handling built in
Production state: zero warnings, full test coverage, security-first defaults

Core Philosophy

UVHTTP follows these principles:

Focus on Core Protocol Handling: HTTP/1.1 and WebSocket processing only; no business logic
Zero Overhead Abstractions: all abstractions are compile-time macros with no runtime cost
Minimalist Engineering: cut unnecessary complexity, keep functionality
Test Separation: production code contains no test-specific code or debug instrumentation
Zero Global Variables: all state held in libuv data pointers for multi-instance support
Error Handling: unified error system with diagnostics and recovery guidance

🏗️ Architecture Overview

Event-Driven Design

UVHTTP uses libuv's event loop for high concurrency without threads:

┌─────────────────────────────────────────────────┐
│           Event Loop (libuv)                    │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
│  │ Timer   │  │  I/O    │  │ Signal  │         │
│  │ Events  │  │ Events  │  │ Events  │         │
│  └────┬────┘  └────┬────┘  └────┬────┘         │
│       │            │            │                │
│  ┌────▼────────────▼────────────▼────┐          │
│  │    HTTP Request Handlers          │          │
│  │  - Route Matching                 │          │
│  │  - Middleware Processing          │          │
│  │  - Response Generation            │          │
│  └───────────────────────────────────┘          │
└─────────────────────────────────────────────────┘

Key Components

Component	Responsibility
Server	HTTP server lifecycle management, connection pooling
Router	O(1) prefix matching for fast route resolution
Connection	TCP connection management with Keep-Alive support
Request/Response	HTTP message parsing and generation
WebSocket	Full-duplex communication over HTTP upgrade
Static Files	Zero-copy file serving with caching
TLS	Encryption layer using mbedtls

🌍 Platform Support

Current Status

Platform	Status	Notes
Linux x86_64	✅ Fully Supported	Primary platform
Linux x86 (32-bit)	✅ Fully Supported	Embedded-optimized
macOS	📋 Planned
Windows	📋 Planned
FreeBSD	📋 Planned	Community requested

Cross-Platform Considerations

UVHTTP is built for portability:

Standard C99: no compiler-specific extensions required
Self-contained dependencies: all external libraries included as submodules
Conditional compilation: platform-specific code isolated behind feature macros
POSIX: uses POSIX APIs where available

🚀 Performance Characteristics

Benchmark Results (v2.7.1)

yaml

Configuration:
  - Server: 4-core CPU, 16GB RAM
  - Client: wrk, 4 threads, 100 connections
  - Test Duration: 30 seconds

HTTP/1.1 Benchmarks:
  Low Concurrency:
    - Throughput: 23,226 RPS
    - Latency: 2.92 ms avg (P50)
    - Error Rate: 0.00%
  
  High Concurrency:
    - Throughput: 31,409 RPS
    - Latency: 43.59 ms avg (P99)
    - Error Rate: 0.00%
  
  Static Files (1MB):
    - Throughput: 12,510 RPS
    - Latency: 15.3 ms avg
    - Zero-Copy: Enabled (sendfile)

API Routing:
  - Throughput: 13,950 RPS
  - Route Lookup: O(1) complexity
  - Middleware Overhead: < 10μs per request

Performance Optimizations

Keep-Alive: connection reuse avoids per-request TCP setup
TCP: TCP_NODELAY and TCP_KEEPALIVE enabled by default
Router: O(1) prefix matching, no linear search
Allocation: optional mimalloc
Direct libuv calls: no abstraction layer between application and libuv
LRU caching: static files cached with preheating
Zero-copy I/O: sendfile for large file transfers

🔒 Security Features

Built-in Security

Buffer Overflow Protection: bounds checking on all buffers
Input Validation: HTTP headers and request data validated
TLS 1.2/1.3 Support: via mbedtls
Memory Safety: AddressSanitizer and Valgrind compatible
Error Handling: detailed errors without information leakage
Resource Limits: configurable connections, headers, and body size

Security Best Practices

// Example: Enable TLS for production deployments
uvhttp_tls_context_t* tls_ctx = NULL;
uvhttp_tls_context_new(&tls_ctx);
uvhttp_tls_context_load_cert_chain(tls_ctx, "server.crt");
uvhttp_tls_context_load_private_key(tls_ctx, "server.key");
server->tls_ctx = tls_ctx;

// Example: Set reasonable resource limits
server->max_connections = 1000;
server->config->max_body_size = 10 * 1024 * 1024; // 10MB

📚 Documentation Structure

User Guides

Quick Start: Get running in 5 minutes
Installation: Detailed installation instructions
First Server: Build your first HTTP server
WebSocket: Real-time communication setup

Core Concepts

Tutorial: Progressive learning from basics to advanced
libuv Data Pointer: Understanding context passing
Middleware System: Request/response processing pipeline
Unified Response Guide: Standard response patterns

Advanced Features

Rate Limit API: Token bucket rate limiting
Static File Server: Efficient file serving
Compression: Zero-overhead compression

Developer Resources

Developer Guide: Development best practices
CMake Configuration: Build system customization
API Reference: Complete API documentation

🛠️ Quick Start Example

#include <uvhttp.h>
#include <uv.h>
#include <string.h>

// Request handler function
int hello_handler(uvhttp_request_t* req, uvhttp_response_t* res) {
    // Set response status
    uvhttp_response_set_status(res, 200);
    
    // Set response headers
    uvhttp_response_set_header(res, "Content-Type", "application/json");
    uvhttp_response_set_header(res, "X-Powered-By", "UVHTTP/2.7.1");
    
    // Set response body
    const char* body = "{\"message\":\"Hello from UVHTTP\",\"version\":\"2.7.1\"}";
    uvhttp_response_set_body(res, body, strlen(body));
    
    // Send response
    return uvhttp_response_send(res);
}

int main() {
    // Create event loop
    uv_loop_t* loop = uv_default_loop();
    
    // Create server
    uvhttp_server_t* server = NULL;
    uvhttp_server_new(loop, &server);
    
    // Create router
    uvhttp_router_t* router = NULL;
    uvhttp_router_new(&router);
    uvhttp_server_set_router(server, router);
    
    // Add route
    uvhttp_router_add_route(router, "/hello", hello_handler);
    
    // Start listening
    int result = uvhttp_server_listen(server, "0.0.0.0", 8080);
    if (result != UVHTTP_OK) {
        fprintf(stderr, "Failed to start server: %s\n", uvhttp_error_string(result));
        return 1;
    }
    
    // Run event loop
    printf("Server listening on http://0.0.0.0:8080\n");
    uv_run(loop, UV_RUN_DEFAULT);
    
    return 0;
}

Compile and Run:

bash

gcc -o server server.c -I./include -L./build/dist/lib -luvhttp -luv
export LD_LIBRARY_PATH=./build/dist/lib:$LD_LIBRARY_PATH
./server

🤝 Community and Support

Contributing

We welcome contributions! Please read our Contributing Guidelines before submitting pull requests.

Getting Help

GitHub Issues: report bugs and request features
Discussions: ask questions and share ideas
Documentation: guides and API reference

License

This project is licensed under the MIT License - see the LICENSE file for details.

Compatibility

Platform Support

Platform	Version	Status
Linux x86_64	2.2.0+	✅ Stable
Linux i386	2.2.0+	✅ Stable
macOS x86_64	2.2.0+	✅ Stable
macOS ARM64	2.2.0+	✅ Stable
Windows x86_64	2.2.0+	⚠️ Experimental

Compiler Support

Compiler	Version	Status
GCC	4.8+	✅ Stable
Clang	3.4+	✅ Stable
MSVC	2019+	⚠️ Experimental

Dependency Versions

Dependency	Version	Status
libuv	1.44.0+	✅ Required
llhttp	8.1.0+	✅ Required
mbedtls	3.0.0+	✅ Optional (TLS)
mimalloc	2.0.0+	✅ Optional (Allocator)
cjson	1.7.0+	✅ Optional (JSON)

📖 Next Steps

Quick Start Guide: Begin building your first server
API Reference: Explore the complete API
Examples: Browse practical examples
Performance Benchmarks: Understand performance characteristics

Introduction to UVHTTP ​

🎯 What is UVHTTP? ​

Core Philosophy ​

🏗️ Architecture Overview ​

Event-Driven Design ​

Key Components ​

🌍 Platform Support ​

Current Status ​

Cross-Platform Considerations ​

🚀 Performance Characteristics ​

Benchmark Results (v2.7.1) ​

Performance Optimizations ​

🔒 Security Features ​

Built-in Security ​

Security Best Practices ​

📚 Documentation Structure ​

User Guides ​

Core Concepts ​

Advanced Features ​

Developer Resources ​

🛠️ Quick Start Example ​

🤝 Community and Support ​

Contributing ​

Getting Help ​

License ​

Compatibility ​

Platform Support ​

Compiler Support ​

Dependency Versions ​

📖 Next Steps ​