libxev-http Examples

Comprehensive examples and demonstrations for the libxev-http framework. This repository showcases how to build high-performance asynchronous HTTP servers in Zig with multiple operation modes, middleware support, and production-ready security features.

✨ What You'll Learn

• Modern Zig Development: Explore Zig 0.14+ features and the standard package manager
• Async HTTP Architecture: Understand high-performance async HTTP server patterns
• Middleware Systems: See how to build and chain middleware for real applications
• Security Best Practices: Learn production-ready security configurations
• libxev-http Mastery: Complete examples of using the libxev-http framework

📚 Examples Included

This repository contains a comprehensive HTTP server example that demonstrates:

• Multiple Operation Modes: Basic, secure, and development configurations
• Route Handling: Static routes, parameterized routes, and HTTP methods
• Middleware Chain: Logging, request ID, security headers, CORS, and custom middleware
• Security Features: Timeout protection, request validation, and size limits
• Error Handling: Graceful error responses and middleware error handling
• File Upload: Validated file upload with custom middleware
• Authentication: Basic HTTP authentication example

🚀 Features

• High-Performance Async Architecture - Built on libxev event loop for high concurrency
• Multiple Operation Modes - Basic mode, secure mode, and development mode
• Middleware System - Support for global and route-specific middleware
• Security Protection - Built-in timeout protection, request validation, and size limits
• Modern Zig - Uses Zig 0.14+ and standard package manager

📦 Installation and Build

Prerequisites

• Zig 0.14.0 or higher
• Network connection (for downloading dependencies)

Build Project

# Clone the project
git clone https://github.com/dg0230/libxev-http-examples.git
cd libxev-http-examples

# Build the project
zig build

# Run tests
zig build test

🎯 Running the Server

Basic Mode (Default)

zig build run
# or
zig build run -- --mode=basic

• Port: 8080
• Max connections: 1000
• Middleware: Logging, request ID generation

Secure Mode

zig build run -- --mode=secure

• Port: 8082
• Max connections: 500
• Strict timeouts and size limits
• Enhanced security middleware
• Additional security endpoints

Development Mode

zig build run -- --mode=dev

• Port: 8081
• Relaxed development settings
• CORS support

📚 API Endpoints

Common Endpoints

Method	Path	Description
GET	/	Home page (HTML interface)
GET	/api/status	Server status information
POST	/api/echo	Echo request body
GET	/users/:id	Get user information

Additional Secure Mode Endpoints

Method	Path	Description
GET	/health	Health check
GET	/config	Server configuration details
POST	/upload	File upload (with validation middleware)
GET	/admin	Admin panel (requires basic auth)
GET	/stress-test	Stress test endpoint

🧪 Testing the API

Status Check

curl http://127.0.0.1:8080/api/status

User Information

curl http://127.0.0.1:8080/users/123

Echo Test

curl -X POST -H "Content-Type: application/json" \
     -d '{"message":"Hello libxev-http!"}' \
     http://127.0.0.1:8080/api/echo

Secure Mode Testing

# Health check
curl http://127.0.0.1:8082/health

# Configuration info
curl http://127.0.0.1:8082/config

# File upload test
curl -X POST -H "Content-Type: text/plain" \
     -d "Test upload content" \
     http://127.0.0.1:8082/upload

🛡️ Secure Mode Features

Secure mode enables the following protection features:

• Connection Timeouts: 20 seconds total connection time
• Request Timeouts: Headers 5s, body 10s
• Idle Timeout: 3 seconds idle connection timeout
• Size Limits:
  • Total request size: 512KB
  • Body size: 5MB
  • Header count: Maximum 50
  • Individual header size: 4KB
  • URI length: 1KB
• Thread Pool: 4 worker threads
• Connection Pool: Maximum 500 connections

🔧 Middleware

The project demonstrates the use of the following middleware:

• Logging Middleware - Logs all requests
• Request ID Middleware - Generates unique ID for each request
• Security Headers Middleware - Adds security-related HTTP headers
• JSON Parser Middleware - Automatically parses JSON request bodies
• Error Handler Middleware - Unified error handling
• CORS Middleware - Cross-Origin Resource Sharing support
• Custom Upload Validation Middleware - File upload validation

📁 Project Structure

libxev-http-examples/
├── build.zig              # Build configuration
├── build.zig.zon          # Dependency management
├── src/
│   └── main.zig           # Main server example
├── LICENSE                # MIT License
└── README.md              # Project documentation

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow Zig coding conventions
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass: zig build test

📄 License

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

🌟 Show Your Support

Give a ⭐️ if this project helped you learn Zig or libxev-http!

🔗 Related Links

• libxev-http - High-performance async HTTP framework
• libxev - Cross-platform event loop library
• Zig - Zig programming language