🔥 Carbon HTTP Server

Features HTTP/2, WebSocket, advanced security, caching, and asynchronous I/O capabilities

⚠️ WORK IN PROGRESS: This project is currently under active development and is not yet a full release. Features may be incomplete, APIs may change, and bugs may be present. Use in production environments at your own risk.

Features • Installation • Configuration • Usage • Contributing • License • Documentation

---

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Project Structure
• Roadmap
• Contributing
• Security
• Documentation
• License
• Acknowledgments

🌟 Overview

Carbon is a modern, production-ready HTTP/HTTPS server implementation in C, designed for high performance and security. Built with modern Linux systems in mind, it features full HTTP/2 support, RFC 6455 compliant WebSocket implementation, epoll-based asynchronous I/O, thread pooling, and comprehensive security measures to deliver a robust web serving solution.

Key Highlights:

• 🚀 HTTP/2 with ALPN - Automatic protocol negotiation, multiplexing, and header compression
• 🔌 WebSocket Support - Real-time bidirectional communication (ws:// and wss://)
• 🔒 Modern Security - SSL/TLS, rate limiting, security headers, memory-safe operations
• ⚡ High Performance - Epoll-based I/O, thread pooling, zero-copy transfers
• 🛠️ Easy Configuration - Linux-style config files, comprehensive documentation

✨ Features

🚀 High Performance

• Asynchronous I/O: Epoll-based event handling for maximum efficiency
• Thread Pool: Efficient connection handling with configurable worker threads
• Memory-Mapped Files: mmap-based file caching for frequently accessed files (up to 10MB)
• Buffer Pooling: Reusable buffer pool to reduce memory allocations
• Smart Caching: Multi-level file caching system to reduce disk I/O
• SendFile Optimization: Zero-copy file transfers for better throughput
• Gzip Compression: Dynamic compression for text-based content
• Keep-Alive Support: Persistent connections to reduce overhead
• TCP Optimization: Fine-tuned NODELAY, TCP_QUICKACK, and buffer configurations
• CPU Affinity: Thread-to-core pinning for better cache utilization
• Dynamic Rate Limiting: CPU-based adaptive rate limiting

🔒 High Security

• SSL/TLS Support: Full HTTPS support with modern cipher suites
• Auto HTTPS Redirect: Automatic HTTP to HTTPS redirection
• Rate Limiting: Per-IP rate limiting and DDoS protection
• Security Headers: CSP, HSTS, X-Frame-Options, and more
• Input Sanitization: Protection against path traversal and injection attacks
• Buffer Overflow Prevention: Memory-safe operations throughout
• Memory Leak Prevention: Comprehensive resource management and cleanup

🌐 Modern Web Features

• HTTP/2 Support: Full HTTP/2 implementation with ALPN negotiation
• WebSocket Support: Full RFC 6455 compliant WebSocket implementation
• Secure WebSockets (wss://): Encrypted WebSocket connections over TLS
• Protocol Negotiation: Automatic HTTP/2 or HTTP/1.1 via ALPN
• Real-time Communication: Bidirectional messaging with WebSocket frames
• Binary & Text Frames: Support for all WebSocket frame types (text, binary, ping, pong, close)

🛠️ Developer Features

• Linux-Style Configuration: Easy-to-edit .conf files with comments
• Comprehensive Logging: Detailed logs with rotation support
• MIME Type Detection: Automatic content-type detection via libmagic
• Debug Mode: Built-in debugging support for development
• Echo Server: Built-in WebSocket echo server for testing

📦 Prerequisites

Before building Carbon, ensure you have the following dependencies installed:

# Update package lists
sudo apt-get update

# Install required dependencies
sudo apt-get install -y \
    build-essential \
    libssl-dev \
    libmagic-dev \
    libnghttp2-dev \
    zlib1g-dev \
    pkg-config

🚀 Installation

Using HTTP configuration

# Clone the repository
git clone https://github.com/Azreyo/Carbon.git
cd Carbon

# Install dependencies
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev libmagic-dev libnghttp2-dev zlib1g-dev pkg-config

# Build the server
make

# Run the server
sudo ./server

Build Options

Carbon provides multiple build configurations:

make              # Standard build
make debug        # Debug build with symbols
make release      # Optimized release build
make clean        # Clean build artifacts
make install-deps # Install all dependencies (Debian systems only)

Using Docker

Carbon includes full Docker support for easy deployment:

# Using Docker Compose (recommended)
docker-compose up -d

# Or build and run manually
docker build -t carbon-server .
docker run -d -p 8080:8080 -p 8443:8443 \
  -e PORT=8080 \
  -e USE_HTTPS=false \
  -e ENABLE_HTTP2=false \
  -e ENABLE_WEBSOCKET=false \
  carbon-server

# Using the official image
docker pull azreyo/carbon:latest
docker run -d -p 8080:8080 azreyo/carbon:latest

Docker Environment Variables:

• SERVER_NAME: Server domain/IP (default: 0.0.0.0)
• PORT: Server port (default: 8080)
• USE_HTTPS: Enable HTTPS (default: false)
• ENABLE_HTTP2: Enable HTTP/2 (default: false)
• ENABLE_WEBSOCKET: Enable WebSocket (default: false)
• MAX_THREADS: Worker threads (default: 4)
• VERBOSE: Verbose logging (default: true)

Manual Compilation

If you prefer manual compilation:

gcc src/server.c src/config_parser.c src/server_config.c src/websocket.c src/http2.c src/performance.c -o server \
    -D_GNU_SOURCE \
    -Wall -Wextra -O2 \
    -lssl -lcrypto -lpthread -lmagic -lnghttp2 -lz

⚙️ Configuration

SSL/TLS Setup

⚠️ Important: Self-signed certificates should only be used for testing purposes. For production, use certificates from a trusted Certificate Authority like Let's Encrypt.

# Create certificates directory
mkdir -p ssl/cert ssl/key

# Generate self-signed certificate (for testing only)
openssl req -x509 -newkey rsa:2048 \
    -keyout ssl/key/key.key \
    -out ssl/cert/cert.pem \
    -days 365 -nodes \
    -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

Server Configuration

Create or edit server.conf in the project root. Carbon uses a traditional Linux-style configuration format with key = value pairs:

# Carbon Web Server Configuration File
# Lines starting with # are comments

# Server running state
running = true

# ---Network configuration---
# Server listening port
port = 8080
# Enable HTTPS (requires valid certificates in certs/ directory)
use_https = false
# Enable HTTP/2 support (requires HTTPS)
enable_http2 = false
# Enable WebSocket support
enable_websocket = false
# Server name or IP address (used for logging and response headers)
server_name = Your_domain/IP

# ---Performance configuration---
# Maximum number of worker threads
max_threads = 4
max_connections = 1024

# ---Path configuration---
# Log file location
log_file = log/server.log
# Enable verbose logging
verbose = true
# Path to www directory
www_path = www
# Path to public ssl certificate
ssl_cert_path = ssl/cert/cert.pem
# Path to private ssl key
ssl_key_path = ssl/key/key.key

Configuration Options:

• running: Server running state (default: true)
• port: HTTP/HTTPS port (default: 8080)
• use_https: Enable HTTPS - accepts: true/false, yes/no, on/off, 1/0 (requires SSL certificates)
• enable_http2: Enable HTTP/2 support (requires HTTPS and ALPN, default: false)
• enable_websocket: Enable WebSocket support (default: false)
• server_name: Your domain or IP address
• max_threads: Number of worker threads (default: 4)
• max_connections: Maximum concurrent connections (default: 1024)
• log_file: Path to log file (default: log/server.log)
• verbose: Enable detailed logging - accepts: true/false, yes/no, on/off, 1/0
• www_path: Path to web root directory (default: www)
• ssl_cert_path: Path to SSL certificate file (default: ssl/cert/cert.pem)
• ssl_key_path: Path to SSL private key file (default: ssl/key/key.key)

Note: Boolean values are flexible and accept multiple formats:

• True: true, yes, on, 1
• False: false, no, off, 0

Values can optionally be quoted with single or double quotes.

Directory Structure

Set up the required directory structure:

# Create web root and subdirectories
mkdir -p www/{css,js,images}

# Create logs directory
mkdir -p log

🎯 Usage

Starting the Server

# Run the server
./server

# The server will start on the configured port (default: 8080)
# Access it at http://localhost:8080

Firewall Configuration

If you're using UFW, allow the necessary ports:

# Allow HTTP port
sudo ufw allow 8080/tcp

# Allow HTTPS port (if using SSL)
sudo ufw allow 443/tcp

# Reload firewall
sudo ufw reload

Testing

# Test HTTP endpoint
curl http://localhost:8080

# Test HTTPS endpoint (if enabled)
curl -k https://localhost:443

# Test HTTP/2 (requires HTTPS)
curl --http2 -k https://localhost:443

# Verify HTTP/2 negotiation
openssl s_client -connect localhost:443 -alpn h2 < /dev/null 2>&1 | grep "ALPN protocol"

WebSocket Usage

Carbon includes full WebSocket support for real-time bidirectional communication.

JavaScript Client Example:

// Connect to WebSocket server
const ws = new WebSocket('ws://localhost:8080');

// Connection opened
ws.addEventListener('open', (event) => {
    console.log('Connected to server');
    ws.send('Hello Server!');
});

// Listen for messages
ws.addEventListener('message', (event) => {
    console.log('Message from server:', event.data);
});

// Handle errors
ws.addEventListener('error', (error) => {
    console.error('WebSocket error:', error);
});

// Connection closed
ws.addEventListener('close', (event) => {
    console.log('Disconnected from server');
});

Secure WebSocket (wss://):

const wss = new WebSocket('wss://your-domain.com');
// Same API as above

Testing with wscat:

# Install wscat
npm install -g wscat

# Connect to WebSocket server
wscat -c ws://localhost:8080

# Connect to secure WebSocket
wscat -c wss://localhost:443 --no-check

# Type messages and press Enter to send
# The server will echo them back

Python Client Example:

import websocket

def on_message(ws, message):
    print(f"Received: {message}")

def on_open(ws):
    print("Connected")
    ws.send("Hello from Python!")

ws = websocket.WebSocketApp("ws://localhost:8080",
                           on_message=on_message,
                           on_open=on_open)
ws.run_forever()

HTTP/2 Support

Carbon includes full HTTP/2 support with automatic protocol negotiation via ALPN.

Features:

• ✅ HTTP/2 server push (stream multiplexing)
• ✅ HPACK header compression
• ✅ Binary framing protocol
• ✅ Automatic fallback to HTTP/1.1
• ✅ ALPN protocol negotiation
• ✅ Server-side stream management

Configuration:

Enable HTTP/2 in server.conf:

use_https = true
enable_http2 = true
https_port = 443

Testing HTTP/2:

# Test with curl (verbose)
curl -v --http2 -k https://localhost:443/

# Check ALPN negotiation
openssl s_client -connect localhost:443 -alpn h2 < /dev/null 2>&1 | grep "ALPN protocol"

# Test with h2load (load testing)
h2load -n 1000 -c 10 https://localhost:443/

# Use the diagnostic script
./check-http2.sh

Browser Support:

All modern browsers support HTTP/2:

• ✅ Chrome/Chromium 40+
• ✅ Firefox 36+
• ✅ Safari 9+
• ✅ Edge (all versions)
• ✅ Opera 27+

Browsers automatically negotiate HTTP/2 when connecting to HTTPS sites that support it.

Performance Benefits:

HTTP/2 provides significant performance improvements:

• Multiplexing: Multiple requests over a single connection
• Header Compression: Reduced overhead with HPACK
• Server Push: Proactive resource delivery
• Binary Protocol: More efficient parsing
• Stream Prioritization: Better resource loading

📁 Project Structure

Carbon/
├── src/
│   ├── server.c          # Main server implementation
│   ├── server_config.c   # Configuration management
│   ├── server_config.h   # Configuration headers
│   ├── config_parser.c   # Configuration file parser
│   ├── websocket.c       # WebSocket implementation
│   ├── websocket.h       # WebSocket headers
│   ├── http2.c           # HTTP/2 implementation
│   ├── http2.h           # HTTP/2 headers
│   ├── performance.c     # Performance optimizations
│   ├── performance.h     # Performance headers
│   └── bin/              # Compiled object files
├── Makefile              # Build configuration
├── Dockerfile            # Docker container configuration
├── docker-compose.yml    # Docker Compose configuration
├── docker-push.sh        # Docker image push script
├── server.conf           # Server configuration file (Linux-style)
├── README.md             # This file
├── DOCUMENTATION.md      # Comprehensive documentation
├── LICENSE               # MIT License
├── ssl/                  # SSL certificates directory (create this)
│   ├── cert/
│   │   └── cert.pem      # SSL certificate
│   └── key/
│       └── key.key       # SSL private key
├── www/                  # Web root directory
│   ├── index.html
│   └── websocket-test.html  # WebSocket test client
└── log/                  # Log files
    └── server.log

🗺️ Roadmap

Feature	Priority	Status
HTTP/2 Support	High	✅ Implemented
WebSocket Support	High	✅ Implemented
Secure WebSocket (wss://)	High	✅ Implemented
API Rate Limiting	High	✅ Implemented
Security Headers	High	✅ Implemented
Memory Leak Prevention	High	✅ Implemented
Performance Optimizations	High	✅ Implemented
File Caching (mmap)	High	✅ Implemented
Buffer Pooling	High	✅ Implemented
Docker Support	Medium	✅ Implemented
Gzip Compression	Medium	✅ Implemented
User Authentication	High	📋 Planned
Reverse Proxy Mode	Medium	📋 Planned
Load Balancing	Low	📋 Planned
Comprehensive API Docs	Medium	🔄 In Progress

🤝 Contributing

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

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

Please ensure your code:

• Follows the existing code style
• Includes appropriate comments
• Passes all tests
• Updates documentation as needed

🔐 Security

Carbon implements multiple security layers, but for production deployments:

• ✅ Use a reverse proxy (Nginx, Apache) for additional security
• ✅ Obtain proper SSL certificates from Let's Encrypt or another CA
• ✅ Keep dependencies updated regularly
• ✅ Monitor server logs for suspicious activity
• ✅ Conduct regular security audits
• ✅ Implement firewall rules to restrict access
• ✅ Use strong passwords and authentication mechanisms

Reporting Security Issues: Please report security vulnerabilities to the maintainers privately before public disclosure.

📚 Documentation

Detailed documentation on how to use carbon server - see the Documentation for more details.

📄 License

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

🙏 Acknowledgments

Carbon is built with these excellent open-source libraries:

• OpenSSL - SSL/TLS cryptography and ALPN support
• nghttp2 - HTTP/2 protocol implementation
• libmagic - MIME type detection

---

Made with ❤️ by Azreyo

⭐ Star this repository if you find it helpful!