libxev-http

A high-performance async HTTP framework for Zig built on top of libxev.

✨ Features

• ⚡ Async Event-Driven: Built on libxev for maximum performance and scalability
• 🛣️ Advanced Routing: Parameter extraction, wildcards, and middleware support
• 🔧 Flexible Middleware: Global and route-specific middleware with built-in common functionality
• 🛡️ Built-in Protection: Comprehensive timeout protection and request validation
• ⚙️ Flexible Configuration: Multiple preset configurations for different environments
• 🔒 Memory Safe: Comprehensive resource management and security validation
• 🌍 Cross-Platform: Supports Linux (io_uring/epoll), macOS (kqueue), and Windows (IOCP)
• 📦 Production Ready: Battle-tested HTTP parsing and response building

🚀 Quick Start

Installation

Add libxev-http to your project using git submodules:

git submodule add https://github.com/mitchellh/libxev.git libxev

Try the Examples

# Clone the repository
git clone <repository-url>
cd libxev-http

# Run the multi-mode example server
zig build run-basic                    # Basic mode (port 8080)
zig build run-basic -- --mode=secure  # Secure mode (port 8082)
zig build run-basic -- --mode=dev     # Development mode

# Run tests
zig build test-all

# See all available commands
zig build help

Basic Usage

const std = @import("std");
const libxev_http = @import("libxev-http");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create HTTP server with default configuration
    var server = try libxev_http.createServer(allocator, "127.0.0.1", 8080);
    defer server.deinit();

    // Add global middleware
    try server.use("logging", libxev_http.loggingMiddleware);
    try server.use("request-id", libxev_http.requestIdMiddleware);
    try server.use("cors", libxev_http.corsMiddleware);

    // Set up routes
    _ = try server.get("/", indexHandler);
    _ = try server.get("/api/status", statusHandler);
    _ = try server.post("/api/echo", echoHandler);
    _ = try server.get("/users/:id", userHandler);

    // Start listening
    try server.listen();
}

fn indexHandler(ctx: *libxev_http.Context) !void {
    try ctx.html("<h1>Hello, libxev-http!</h1>");
}

fn statusHandler(ctx: *libxev_http.Context) !void {
    try ctx.json("{\"status\":\"ok\",\"server\":\"libxev-http\"}");
}

fn echoHandler(ctx: *libxev_http.Context) !void {
    const body = ctx.getBody() orelse "No body";
    try ctx.text(body);
}

fn userHandler(ctx: *libxev_http.Context) !void {
    const user_id = ctx.getParam("id") orelse "unknown";
    const response = try std.fmt.allocPrint(ctx.allocator,
        "{{\"user_id\":\"{s}\"}}", .{user_id});
    defer ctx.allocator.free(response);
    try ctx.json(response);
}

Advanced Configuration

const std = @import("std");
const libxev_http = @import("libxev-http");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Custom configuration for production
    const config = libxev_http.HttpConfig{
        .connection_timeout_ms = 30000,      // 30 seconds
        .request_timeout_ms = 30000,         // 30 seconds
        .header_timeout_ms = 10000,          // 10 seconds
        .body_timeout_ms = 60000,            // 60 seconds
        .idle_timeout_ms = 5000,             // 5 seconds
        .max_request_size = 1024 * 1024,     // 1MB
        .max_body_size = 10 * 1024 * 1024,   // 10MB
        .enable_request_validation = true,
        .enable_timeout_protection = true,
    };

    // Create server with custom configuration
    var server = try libxev_http.createServerWithConfig(
        allocator,
        "127.0.0.1",
        8080,
        config
    );
    defer server.deinit();

    // Set up routes...
    try server.listen();
}

Preset Configurations

// Development configuration (relaxed timeouts, detailed logging)
const dev_config = libxev_http.HttpConfig.development();

// Production configuration (balanced settings)
const prod_config = libxev_http.HttpConfig.production();

// Testing configuration (fast timeouts, small limits)
const test_config = libxev_http.HttpConfig.testing();

🔧 Middleware System

libxev-http provides a powerful middleware system for request/response processing:

Global Middleware

var server = try libxev_http.createServer(allocator, "127.0.0.1", 8080);

// Add global middleware (applies to all routes)
try server.use("logging", libxev_http.loggingMiddleware);
try server.use("request-id", libxev_http.requestIdMiddleware);
try server.use("cors", libxev_http.corsMiddleware);
try server.use("security", libxev_http.securityHeadersMiddleware);

Route-Specific Middleware

// Create a protected route
const protected_route = try server.get("/api/protected", protectedHandler);

// Add middleware to this specific route
try protected_route.use("auth", libxev_http.basicAuthMiddleware);
try protected_route.use("rate-limit", libxev_http.rateLimitMiddleware);

Custom Middleware

fn customMiddleware(ctx: *libxev_http.Context, next: libxev_http.NextFn) !void {
    // Pre-processing
    try ctx.setHeader("X-Custom", "middleware-executed");

    // Call next middleware/handler
    try next(ctx);

    // Post-processing (optional)
}

// Use custom middleware
try server.use("custom", customMiddleware);

Built-in Middleware

• loggingMiddleware: Request logging with timing
• requestIdMiddleware: Unique request ID generation
• corsMiddleware: CORS headers support
• securityHeadersMiddleware: Security headers (XSS, CSRF protection)
• basicAuthMiddleware: HTTP Basic authentication
• jsonBodyParserMiddleware: JSON request validation
• rateLimitMiddleware: Rate limiting headers
• errorHandlerMiddleware: Error handling and recovery
• compressionMiddleware: Response compression support

🛡️ Built-in Protection

libxev-http includes comprehensive protection features:

Timeout Protection

• Connection timeout: Limits total connection lifetime
• Request timeout: Limits time to receive complete request
• Header timeout: Limits time to receive HTTP headers
• Body timeout: Limits time to receive request body
• Idle timeout: Limits connection idle time

Request Validation

• Size limits: Configurable limits for requests, headers, URI, and body
• Format validation: Validates HTTP request format
• Progress monitoring: Monitors request reception progress

Configuration Examples

// High-security configuration
const secure_config = libxev_http.HttpConfig{
    .connection_timeout_ms = 10000,       // 10 seconds
    .header_timeout_ms = 3000,            // 3 seconds
    .body_timeout_ms = 5000,              // 5 seconds
    .max_request_size = 256 * 1024,       // 256KB
    .max_body_size = 1024 * 1024,         // 1MB
    .enable_keep_alive = false,           // Disable keep-alive
};

// High-performance configuration
const performance_config = libxev_http.HttpConfig{
    .connection_timeout_ms = 60000,       // 60 seconds
    .header_timeout_ms = 20000,           // 20 seconds
    .body_timeout_ms = 120000,            // 120 seconds
    .max_request_size = 10 * 1024 * 1024, // 10MB
    .max_body_size = 100 * 1024 * 1024,   // 100MB
};

📚 API Reference

Server Creation

// Basic server with default configuration
var server = try libxev_http.createServer(allocator, "127.0.0.1", 8080);

// Server with custom configuration
var server = try libxev_http.createServerWithConfig(allocator, "127.0.0.1", 8080, config);

// Add routes
_ = try server.get("/path", handler);
_ = try server.post("/path", handler);
_ = try server.put("/path", handler);
_ = try server.delete("/path", handler);

// Start server
try server.listen();

Context

fn handler(ctx: *libxev_http.Context) !void {
    // Request information
    const method = ctx.getMethod();
    const path = ctx.getPath();
    const body = ctx.getBody();
    const header = ctx.getHeader("Content-Type");

    // Route parameters
    const id = ctx.getParam("id");

    // Response helpers
    ctx.status(.ok);
    try ctx.json("{\"message\":\"success\"}");
    try ctx.html("<h1>Hello</h1>");
    try ctx.text("Plain text");

    // Headers
    try ctx.setHeader("X-Custom", "value");

    // Redirect
    try ctx.redirect("/new-path", .moved_permanently);
}

Routing

// Exact routes
_ = try server.get("/users", listUsers);

// Parameter routes
_ = try server.get("/users/:id", getUser);
_ = try server.get("/users/:id/posts/:post_id", getUserPost);

// Wildcard routes
_ = try server.get("/static/*", serveStatic);

🏗️ Architecture

The framework is built with a modular architecture:

• lib.zig: Main server implementation and public API
• request.zig: HTTP request parsing with security validation
• response.zig: HTTP response building with headers and cookies
• router.zig: High-performance routing with parameter extraction
• context.zig: Request context management and response helpers
• middleware.zig: Flexible middleware system with built-in common functionality
• security.zig: Timeout protection and request validation
• config.zig: Configuration management and presets
• buffer.zig: Efficient buffer management

🧪 Testing and Development

Running Tests

# Quick tests (core + integration)
zig build test-quick

# Run all tests (comprehensive)
zig build test-all

# Run specific module tests
zig build test-security          # Security and timeout protection
zig build test-router            # Routing functionality
zig build test-middleware        # Middleware system
zig build test-request           # HTTP request parsing
zig build test-response          # HTTP response building

# Run with coverage analysis
zig build test-coverage

Development Server

# Multi-mode example server
zig build run-basic                    # Basic mode (port 8080)
zig build run-basic -- --mode=secure  # Secure mode (port 8082)
zig build run-basic -- --mode=dev     # Development mode

# See all available commands
zig build help

Build Options

# Debug build (default)
zig build

# Release builds
zig build --release=fast      # Optimized for speed
zig build --release=safe      # Optimized with safety checks
zig build --release=small     # Optimized for size

# Cross-compilation
zig build -Dtarget=x86_64-linux
zig build -Dtarget=x86_64-windows

📖 Examples and Documentation

Example Server

The examples/basic_server.zig provides a comprehensive multi-mode example:

• Basic Mode: Standard configuration for general use
• Secure Mode: Strict timeouts and limits for high-security environments
• Development Mode: Relaxed settings for development and debugging

# Try different modes
zig build run-basic -- --mode=basic    # Port 8080
zig build run-basic -- --mode=secure   # Port 8082, strict limits
zig build run-basic -- --mode=dev      # Port 8080, relaxed settings

Available Endpoints

When running the example server:

Basic/Dev Mode:

• GET / - Server information and mode details
• GET /api/status - Server status JSON
• POST /api/echo - Echo request body
• GET /users/:id - User information with parameter

Secure Mode (additional):

• GET /health - Health check endpoint
• GET /config - Configuration details
• POST /upload - File upload with size validation
• GET /stress-test - Timeout testing endpoint

Documentation

• Middleware System: Complete guide to the middleware system
• Timeout Protection: Comprehensive guide to timeout protection and request validation
• Multi-Mode Example: Detailed explanation of the example server modes
• Build System: Complete build system documentation

🚀 Performance

libxev-http is designed for high performance:

• Async I/O: Built on libxev's efficient event loop
• Zero-copy parsing: Minimal memory allocations during request parsing
• Connection pooling: Efficient connection management
• Timeout protection: Prevents resource exhaustion with minimal overhead
• Cross-platform: Optimized for each platform's best I/O mechanism

Benchmarks

Performance characteristics (typical results):

• Memory overhead: < 64 bytes per connection for timeout tracking
• CPU overhead: < 0.1% for security validation
• Throughput: Scales with available CPU cores and I/O capacity

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Development Setup

# Clone the repository
git clone <repository-url>
cd libxev-http

# Run tests to ensure everything works
zig build test-all

# Start development server
zig build run-basic -- --mode=dev

📄 License

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

🙏 Acknowledgments

• Built on top of libxev by Mitchell Hashimoto
• Inspired by modern HTTP frameworks across different languages
• Designed with security and performance as primary concerns

---

libxev-http - High-performance async HTTP framework for Zig with built-in protection 🚀🛡️