diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..382d4f3 --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,931 @@ +# Carbon HTTP Server - Complete Documentation +> ⚠️ Warning some features are not implemented yet in the documentation and can be broken. Work in progress + +> ⚒️ Features that are WIP will be marked. +## Table of Contents + +1. [Introduction](#introduction) +2. [Architecture Overview](#architecture-overview) +3. [Installation & Setup](#installation--setup) +4. [Configuration Reference](#configuration-reference) +5. [API Reference](#api-reference) +6. [HTTP/2 Implementation](#http2-implementation) +7. [WebSocket Implementation](#websocket-implementation) +8. [Security Features](#security-features) +9. [Performance Tuning](#performance-tuning) +10. [Troubleshooting](#troubleshooting) +11. [Development Guide](#development-guide) + +--- + +## Introduction + +Carbon is a high-performance HTTP/HTTPS server written in C for Linux systems. It provides modern web server capabilities including HTTP/2, WebSocket support, SSL/TLS encryption, and advanced security features. + +### Key Features + +- **HTTP/2 Protocol**: Full implementation with ALPN negotiation, multiplexing, and HPACK compression +- **WebSocket Support**: RFC 6455 compliant with secure WebSocket (wss://) support +- **SSL/TLS Encryption**: OpenSSL integration with modern cipher suites +- **Asynchronous I/O**: Epoll-based event handling for high concurrency +- **Thread Pooling**: Efficient multi-threaded request handling +- **Security**: Rate limiting, security headers, input sanitization, memory safety + +### System Requirements + +- **Operating System**: Linux (kernel 2.6.27+) +- **Compiler**: GCC 4.8+ or Clang 3.4+ +- **Dependencies**: + - OpenSSL 1.1.0+ (libssl-dev) + - libmagic (libmagic-dev) + - nghttp2 1.0.0+ (libnghttp2-dev) + - pthread (usually included) + +--- + +## Architecture Overview + +### Server Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Carbon HTTP Server │ +├─────────────────────────────────────────────────────────────┤ +│ Main Thread (Epoll Event Loop) │ +│ ├─── Socket Management │ +│ ├─── Connection Acceptance │ +│ └─── Event Distribution │ +├─────────────────────────────────────────────────────────────┤ +│ Worker Thread Pool │ +│ ├─── HTTP/1.1 Handler │ +│ ├─── HTTP/2 Handler (nghttp2) │ +│ ├─── WebSocket Handler │ +│ └─── SSL/TLS Handler (OpenSSL) │ +├─────────────────────────────────────────────────────────────┤ +│ Core Services │ +│ ├─── Configuration Manager │ +│ ├─── Logging System │ +│ ├─── Rate Limiter │ +│ ├─── File Cache │ +│ └─── MIME Type Detection │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Request Flow + +1. **Connection Acceptance**: Main thread accepts incoming connections via epoll +2. **SSL/TLS Handshake**: If HTTPS is enabled, OpenSSL performs handshake +3. **Protocol Negotiation**: ALPN determines HTTP/2 or HTTP/1.1 +4. **Request Processing**: Worker thread handles the request +5. **Response Generation**: Content is prepared and sent to client +6. **Connection Management**: Keep-alive or close based on protocol + +### File Structure + +``` +Carbon/ +├── src/ +│ ├── server.c # Main server implementation +│ ├── server_config.h # Configuration structures +│ ├── server_config.c # Configuration management +│ ├── config_parser.c # Config file parser +│ ├── http2.c # HTTP/2 implementation +│ ├── http2.h # HTTP/2 headers +│ ├── websocket.c # WebSocket implementation +│ └── websocket.h # WebSocket headers +├── www/ # Web root directory +├── certs/ # SSL certificates +├── log/ # Log files +├── Makefile # Build configuration +└── server.conf # Server configuration +``` + +--- + +## Installation & Setup + +### Quick Installation + +```bash +# Install dependencies +sudo apt-get update +sudo apt-get install -y build-essential libssl-dev libmagic-dev libnghttp2-dev + +# Clone and build +git clone https://github.com/Azreyo/Carbon.git +cd Carbon +make + +# Setup directories +mkdir -p certs log www + +# Generate test certificates +openssl req -x509 -nodes -days 365 -newkey rsa:4096 \ + -keyout certs/key.pem -out certs/cert.pem \ + -subj "/C=US/ST=State/L=City/O=Carbon/CN=localhost" + +# Run server +sudo ./server +``` + +### Build Options + +```bash +make # Standard build (-O2 optimization) +make debug # Debug build with symbols (-g -O0) +make release # Release build with optimizations (-O3) +make clean # Remove build artifacts +``` + +### Production Setup + +For production environments: + +1. **Use Let's Encrypt certificates** (see [LETSENCRYPT_SETUP.md](LETSENCRYPT_SETUP.md)) +2. **Configure firewall rules**: + ```bash + sudo ufw allow 80/tcp + sudo ufw allow 443/tcp + sudo ufw enable + ``` +3. **Set up as systemd service**: + ```bash + sudo cp carbon.service /etc/systemd/system/ + sudo systemctl enable carbon + sudo systemctl start carbon + ``` +4. **Configure log rotation** (see [Logging](#logging) section) + +--- + +## Configuration Reference + +### Configuration File Format + +Carbon uses a Linux-style configuration file (`server.conf`) with `key = value` pairs. Lines starting with `#` are comments. + +### Configuration Options + +#### Network Settings + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `port` | integer | 8080 | HTTP port to listen on | +| `https_port` | integer | 443 | HTTPS port to listen on | +| `use_https` | boolean | false | Enable HTTPS | +| `server_name` | string | localhost | Server hostname or IP | + +#### Protocol Settings + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `enable_http2` | boolean | true | Enable HTTP/2 (requires HTTPS) | +| `enable_websocket` | boolean | true | Enable WebSocket support | + +#### Performance Settings + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `max_threads` | integer | 4 | Number of worker threads | +| `keep_alive_timeout` | integer | 60 | Keep-alive timeout in seconds | +| `max_connections` | integer | 1000 | Maximum concurrent connections | + +#### Logging Settings + +> ⚠️ Work in progress + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `log_file` | string | log/server.log | Path to log file | +| `verbose` | boolean | false | Enable verbose logging | + +#### Security Settings + +> ⚠️ Work in progress + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `rate_limit` | integer | 100 | Requests per IP per minute | +| `enable_hsts` | boolean | true | Enable HSTS header | +| `enable_csp` | boolean | true | Enable CSP header | + +### Boolean Value Formats + +Boolean options accept multiple formats: +- **True**: `true`, `yes`, `on`, `1` +- **False**: `false`, `no`, `off`, `0` + +Values can be quoted with single or double quotes. + +### Example Configuration + +```conf +# Carbon Web Server Configuration + +# Network +port = 8080 +https_port = 443 +use_https = true +server_name = example.com + +# Protocols +enable_http2 = true +enable_websocket = true + +# Performance +max_threads = 8 +keep_alive_timeout = 60 +max_connections = 2000 + +# Logging +log_file = /var/log/carbon/server.log +verbose = false + +# Security +rate_limit = 100 +enable_hsts = true +enable_csp = true +``` + +--- + +## API Reference + +### Configuration API +> ⚠️ Work in progress + +#### `parse_config(const char *filename, server_config_t *config)` + +Parse configuration file and populate config structure. + +**Parameters:** +- `filename`: Path to configuration file +- `config`: Pointer to server_config_t structure + +**Returns:** 0 on success, -1 on error + +**Example:** +```c +server_config_t config; +if (parse_config("server.conf", &config) != 0) { + fprintf(stderr, "Failed to parse configuration\n"); + return 1; +} +``` + +#### `parse_boolean(const char *value)` + +Parse boolean value from configuration. + +**Parameters:** +- `value`: String value to parse + +**Returns:** 1 for true, 0 for false + +**Accepted Values:** +- True: "true", "yes", "on", "1" +- False: "false", "no", "off", "0" + +### HTTP/2 API + +#### `http2_session_init(http2_session_t *session, int socket_fd, SSL *ssl)` + +Initialize HTTP/2 session. + +**Parameters:** +- `session`: Pointer to http2_session_t structure +- `socket_fd`: Socket file descriptor +- `ssl`: SSL connection (or NULL for plain HTTP) + +**Returns:** 0 on success, -1 on error + +#### `http2_handle_connection(http2_session_t *session)` + +Handle HTTP/2 connection event loop. + +**Parameters:** +- `session`: Pointer to initialized http2_session_t + +**Returns:** 0 on completion, -1 on error + +#### `http2_session_cleanup(http2_session_t *session)` + +Clean up HTTP/2 session resources. + +**Parameters:** +- `session`: Pointer to http2_session_t to clean up + +### WebSocket API + +#### `ws_handle_handshake(int socket_fd, SSL *ssl, const char *request)` + +Handle WebSocket upgrade handshake. + +**Parameters:** +- `socket_fd`: Socket file descriptor +- `ssl`: SSL connection (or NULL for plain WS) +- `request`: HTTP upgrade request + +**Returns:** 0 on success, -1 on error + +#### `ws_parse_frame(const uint8_t *data, size_t len, ws_frame_t *frame)` + +Parse WebSocket frame from raw data. + +**Parameters:** +- `data`: Raw frame data +- `len`: Length of data +- `frame`: Pointer to ws_frame_t structure to populate + +**Returns:** Number of bytes parsed, -1 on error + +#### `ws_send_frame(ws_connection_t *conn, uint8_t opcode, const uint8_t *payload, size_t payload_len)` + +Send WebSocket frame to client. + +**Parameters:** +- `conn`: WebSocket connection context +- `opcode`: Frame opcode (WS_OPCODE_TEXT, WS_OPCODE_BINARY, etc.) +- `payload`: Frame payload data +- `payload_len`: Length of payload + +**Returns:** Number of bytes sent, -1 on error + +**Opcodes:** +- `WS_OPCODE_CONTINUATION` (0x0): Continuation frame +- `WS_OPCODE_TEXT` (0x1): Text frame +- `WS_OPCODE_BINARY` (0x2): Binary frame +- `WS_OPCODE_CLOSE` (0x8): Close frame +- `WS_OPCODE_PING` (0x9): Ping frame +- `WS_OPCODE_PONG` (0xA): Pong frame + +--- + +## HTTP/2 Implementation + +### Protocol Features + +Carbon's HTTP/2 implementation includes: + +- **ALPN Negotiation**: Automatic protocol selection during TLS handshake +- **Binary Framing**: Efficient binary protocol implementation +- **Stream Multiplexing**: Multiple concurrent requests over single connection +- **HPACK Compression**: Header compression for reduced bandwidth +- **Server Push**: Proactive resource delivery (configurable) +- **Flow Control**: Per-stream and connection-level flow control +- **Priority**: Stream prioritization support + +### HTTP/2 Connection Flow + +1. **TLS Handshake**: Client and server negotiate TLS connection +2. **ALPN Negotiation**: Server advertises "h2" protocol support +3. **Connection Preface**: Client sends HTTP/2 connection preface +4. **Settings Exchange**: Both sides exchange SETTINGS frames +5. **Stream Creation**: Client opens streams with HEADERS frames +6. **Data Transfer**: DATA frames carry request/response bodies +7. **Stream Closure**: Streams closed with END_STREAM flag + +### Configuration + +Enable HTTP/2 in `server.conf`: + +```conf +use_https = true +enable_http2 = true +https_port = 443 +``` + +**Note**: HTTP/2 requires HTTPS and valid SSL certificates. + +### Testing HTTP/2 + +```bash +# Test with curl +curl -v --http2 -k https://localhost:443/ + +# Verify ALPN negotiation +openssl s_client -connect localhost:443 -alpn h2 < /dev/null 2>&1 | grep "ALPN" + +# Load testing with h2load +h2load -n 10000 -c 100 -m 10 https://localhost:443/ + +# Browser DevTools +# Open Chrome DevTools → Network → Protocol column should show "h2" +``` + +### Performance Tuning + +Optimize HTTP/2 performance: + +```conf +# Increase worker threads for concurrent streams +max_threads = 16 + +# Adjust keep-alive for persistent connections +keep_alive_timeout = 120 + +# Increase max connections +max_connections = 5000 +``` + +### Common Issues + +**Issue**: HTTP/2 not negotiated, falling back to HTTP/1.1 +- **Solution**: Ensure HTTPS is enabled and SSL certificates are valid +- **Check**: `openssl s_client -connect host:443 -alpn h2` + +**Issue**: Slow HTTP/2 performance +- **Solution**: Increase `max_threads` in configuration +- **Check**: Monitor CPU usage and adjust accordingly + +--- + +## WebSocket Implementation + +### Protocol Features + +Carbon implements RFC 6455 WebSocket protocol: + +- **Frame Types**: Text, binary, ping, pong, close frames +- **Masking**: Proper client-to-server masking validation +- **Fragmentation**: Support for fragmented messages +- **UTF-8 Validation**: Text frames validated for UTF-8 encoding +- **Secure WebSocket**: wss:// over TLS support +- **Control Frames**: Ping/pong for connection health checks + +### WebSocket Handshake + +1. **HTTP Upgrade**: Client sends HTTP upgrade request +2. **Key Exchange**: Server validates Sec-WebSocket-Key +3. **Accept Response**: Server sends Sec-WebSocket-Accept +4. **Protocol Switch**: Connection switches to WebSocket protocol +5. **Frame Exchange**: Binary frame-based communication begins + +### Server-Side Implementation + +```c +// Check for WebSocket upgrade +if (is_websocket_upgrade(request)) { + // Perform handshake + if (ws_handle_handshake(socket_fd, ssl, request) == 0) { + // Create WebSocket connection + ws_connection_t ws_conn = { + .socket_fd = socket_fd, + .ssl = ssl, + .is_ssl = (ssl != NULL) + }; + + // Handle WebSocket frames + handle_websocket(&ws_conn); + } +} +``` + +### Client-Side Example (JavaScript) + +```javascript +// Create WebSocket connection +const ws = new WebSocket('wss://example.com'); + +// Connection opened +ws.onopen = () => { + console.log('Connected'); + ws.send('Hello Server!'); +}; + +// Receive messages +ws.onmessage = (event) => { + console.log('Received:', event.data); +}; + +// Handle errors +ws.onerror = (error) => { + console.error('WebSocket error:', error); +}; + +// Connection closed +ws.onclose = (event) => { + console.log('Disconnected:', event.code, event.reason); +}; +``` + +### Frame Structure + +WebSocket frames follow this structure: + +``` + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 ++-+-+-+-+-------+-+-------------+-------------------------------+ +|F|R|R|R| opcode|M| Payload len | Extended payload length | +|I|S|S|S| (4) |A| (7) | (16/64) | +|N|V|V|V| |S| | (if payload len==126/127) | +| |1|2|3| |K| | | ++-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - + +| Extended payload length continued, if payload len == 127 | ++ - - - - - - - - - - - - - - - +-------------------------------+ +| |Masking-key, if MASK set to 1 | ++-------------------------------+-------------------------------+ +| Masking-key (continued) | Payload Data | ++-------------------------------- - - - - - - - - - - - - - - - + +: Payload Data continued ... : ++ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +| Payload Data continued ... | ++---------------------------------------------------------------+ +``` + +### Configuration + +Enable WebSocket in `server.conf`: + +```conf +enable_websocket = true +``` + +WebSocket works over both HTTP and HTTPS ports. + +### Testing WebSocket + +```bash +# Install wscat +npm install -g wscat + +# Test WebSocket connection +wscat -c ws://localhost:8080 + +# Test secure WebSocket +wscat -c wss://localhost:443 --no-check + +# Send message +> Hello Server + +# Server echoes back +< Hello Server +``` + +### Common Issues + +**Issue**: WebSocket connection fails with 400 Bad Request +- **Solution**: Ensure Upgrade and Connection headers are present +- **Check**: Request must include `Upgrade: websocket` and `Connection: Upgrade` + +**Issue**: Connection closes immediately +- **Solution**: Check for proper masking in client frames +- **Debug**: Enable verbose logging to see frame details + +--- + +## Security Features + +### SSL/TLS Encryption + +Carbon uses OpenSSL for SSL/TLS encryption: + +- **Protocol Support**: TLS 1.2 and TLS 1.3 +- **Cipher Suites**: Modern, secure ciphers only +- **Perfect Forward Secrecy**: ECDHE key exchange +- **Certificate Validation**: Proper certificate chain validation + +### Security Headers + +Automatically added security headers: + +``` +Content-Security-Policy: default-src 'self' +Strict-Transport-Security: max-age=31536000; includeSubDomains +X-Content-Type-Options: nosniff +X-Frame-Options: DENY +X-XSS-Protection: 1; mode=block +``` + +### Rate Limiting + +Per-IP rate limiting prevents abuse: + +- **Default**: 100 requests per IP per minute +- **Configurable**: Adjust via `rate_limit` setting +- **Automatic Blocking**: Exceeding limit returns 429 Too Many Requests + +### Input Sanitization + +Protection against common attacks: + +- **Path Traversal**: Validates and sanitizes file paths +- **Directory Escapes**: Blocks `..` sequences +- **Null Bytes**: Rejects null bytes in requests +- **Buffer Overflows**: Bounds checking on all buffers + +### Memory Safety + +Memory management practices: + +- **Bounds Checking**: All buffer operations checked +- **Leak Prevention**: Proper resource cleanup +- **Use-After-Free**: Careful pointer management +- **Integer Overflow**: Validation of size calculations + +### Best Practices + +1. **Use Strong Certificates**: Let's Encrypt or commercial CA +2. **Keep Updated**: Regular security updates +3. **Monitor Logs**: Watch for suspicious activity +4. **Firewall Rules**: Restrict access to necessary ports +5. **Reverse Proxy**: Consider Nginx/Apache frontend +6. **Regular Audits**: Periodic security assessments + +--- + +## Performance Tuning + +### Thread Pool Optimization + +```conf +# Adjust based on CPU cores +max_threads = + +# Example for 8-core system +max_threads = 16 +``` + +### Connection Settings + +```conf +# Increase for high-traffic sites +max_connections = 10000 +keep_alive_timeout = 120 +``` + +### System Limits + +Increase system limits for high concurrency: + +```bash +# /etc/security/limits.conf +* soft nofile 65536 +* hard nofile 65536 + +# /etc/sysctl.conf +net.core.somaxconn = 65536 +net.ipv4.tcp_max_syn_backlog = 65536 +net.ipv4.ip_local_port_range = 10000 65535 +``` + +### File Caching + +Enable file caching for static content: +- Frequently accessed files cached in memory +- Reduces disk I/O overhead +- Automatic cache invalidation + +### Zero-Copy Transfers + +Carbon uses `sendfile()` for efficient file transfers: +- Eliminates user-space copies +- Reduces CPU usage +- Improves throughput + +### Benchmarking + +```bash +# Apache Bench +ab -n 10000 -c 100 https://localhost/ + +# wrk +wrk -t 12 -c 400 -d 30s https://localhost/ + +# h2load (HTTP/2) +h2load -n 100000 -c 100 -m 100 https://localhost/ +``` + +--- + +## Troubleshooting + +### Common Issues + +#### Server Won't Start + +**Symptom**: Server exits immediately after starting + +**Solutions**: +1. Check if port is already in use: + ```bash + sudo lsof -i :443 + ``` +2. Verify SSL certificates exist: + ```bash + ls -la certs/ + ``` +3. Check configuration syntax: + ```bash + grep -v '^#' server.conf | grep '=' + ``` + +#### High CPU Usage + +**Symptom**: Server consuming excessive CPU + +**Solutions**: +1. Increase thread pool size +2. Enable keep-alive connections +3. Check for infinite loops in logs +4. Monitor with `top -H -p ` + +#### Memory Leaks + +**Symptom**: Memory usage continuously growing + +**Solutions**: +1. Run with Valgrind: + ```bash + valgrind --leak-check=full ./server + ``` +2. Check error paths for missing `free()` +3. Verify WebSocket connections are properly closed + +#### SSL Handshake Failures + +**Symptom**: Clients can't establish SSL connection + +**Solutions**: +1. Verify certificate validity: + ```bash + openssl x509 -in certs/cert.pem -text -noout + ``` +2. Check certificate chain: + ```bash + openssl verify -CAfile ca.pem certs/cert.pem + ``` +3. Test SSL configuration: + ```bash + openssl s_client -connect localhost:443 + ``` + +### Debug Mode + +Enable debug mode for detailed logging: + +```bash +make clean +make debug +./server +``` + +Debug mode includes: +- Detailed request/response logging +- Frame-level WebSocket logging +- HTTP/2 stream tracking +- Memory allocation tracking + +### Log Analysis + +Monitor logs in real-time: + +```bash +tail -f log/server.log +``` + +Filter for errors: + +```bash +grep ERROR log/server.log +``` + +Count requests by type: + +```bash +grep "Request:" log/server.log | cut -d' ' -f4 | sort | uniq -c +``` + +--- + +## Development Guide + +### Building from Source + +```bash +# Clone repository +git clone https://github.com/Azreyo/Carbon.git +cd Carbon + +# Install development dependencies +sudo apt-get install -y build-essential libssl-dev libmagic-dev libnghttp2-dev + +# Build +make + +# Run tests +make test +``` + +### Code Structure + +#### Adding New Features + +1. **Define interface** in appropriate header file +2. **Implement functionality** in corresponding .c file +3. **Update Makefile** if adding new source files +4. **Add configuration options** if needed +5. **Update documentation** + +#### Example: Adding Custom Header + +```c +// In server.c +void add_custom_header(char *response, const char *name, const char *value) { + char header[256]; + snprintf(header, sizeof(header), "%s: %s\r\n", name, value); + strcat(response, header); +} + +// Usage +add_custom_header(response, "X-Custom-Header", "CustomValue"); +``` + +### Contributing Guidelines + +1. **Fork** the repository +2. **Create feature branch**: `git checkout -b feature/NewFeature` +3. **Follow code style**: 4-space indents, clear variable names +4. **Add comments**: Document complex logic +5. **Test thoroughly**: Ensure no regressions +6. **Update docs**: Keep documentation current +7. **Submit PR**: With clear description + +### Code Style + +```c +// Function naming: lowercase with underscores +int parse_request(const char *data, size_t len); + +// Constants: uppercase with underscores +#define MAX_BUFFER_SIZE 4096 + +// Structs: lowercase with _t suffix +typedef struct { + int socket_fd; + SSL *ssl; +} connection_t; + +// Error handling: always check return values +if (parse_config("server.conf", &config) != 0) { + log_error("Failed to parse configuration"); + return -1; +} +``` + +### Testing + +```bash +# Unit tests +make test + +# Memory leak detection +valgrind --leak-check=full ./server + +# Performance testing +h2load -n 10000 -c 100 https://localhost/ + +# Security scanning +nmap -sV -sC localhost +``` + +--- + +## Appendix + +### Glossary + +- **ALPN**: Application-Layer Protocol Negotiation +- **CSP**: Content Security Policy +- **HPACK**: Header Compression for HTTP/2 +- **HSTS**: HTTP Strict Transport Security +- **TLS**: Transport Layer Security +- **WebSocket**: Full-duplex communication protocol + +### References + +- [RFC 7540](https://tools.ietf.org/html/rfc7540) - HTTP/2 Specification +- [RFC 6455](https://tools.ietf.org/html/rfc6455) - WebSocket Protocol +- [RFC 5246](https://tools.ietf.org/html/rfc5246) - TLS 1.2 +- [RFC 8446](https://tools.ietf.org/html/rfc8446) - TLS 1.3 +- [OpenSSL Documentation](https://www.openssl.org/docs/) +- [nghttp2 Documentation](https://nghttp2.org/documentation/) + +### Support + +- **Issues**: [GitHub Issues](https://github.com/Azreyo/Carbon/issues) +- **Discussions**: [GitHub Discussions](https://github.com/Azreyo/Carbon/discussions) +- **Security**: Report privately to maintainers + +--- + +
+ +**Carbon HTTP Server Documentation** + +Version 0.3.1| October 2025 + +[GitHub](https://github.com/Azreyo/Carbon) • [Issues](https://github.com/Azreyo/Carbon/issues) • [Contributing](CONTRIBUTING.md) + +
diff --git a/README.md b/README.md index 7ad704c..342f533 100644 --- a/README.md +++ b/README.md @@ -3,36 +3,19 @@ # 🔥 Carbon HTTP Server [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -[![Platform](https://img.shields.io/badge/Platform**Configuration Options:** -- `port`: HTTP port (default: 8080) -- `use_https`: Enable HTTPS - accepts: true/false, yes/no, on/off, 1/0 -- `log_file`: Path to log file -- `max_threads`: Number of worker threads -- `server_name`: Your domain or IP address -- `verbose`: Enable detailed logging - accepts: true/false, yes/no, on/off, 1/0 -- `enable_http2`: Enable HTTP/2 support (requires HTTPS) - coming soon -- `enable_websocket`: Enable WebSocket support (default: true) - -**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.svg)](https://www.linux.org/) +[![Platform](https://img.shields.io/badge/Platform-Linux-lightgrey.svg)](https://www.linux.org/) [![Language](https://img.shields.io/badge/Language-C-orange.svg)](https://en.wikipedia.org/wiki/C_(programming_language)) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com) - -**A high-performance HTTP/HTTPS server written in C for Linux systems** - -*Features HTTP/2, WebSocket, advanced security, caching, and asynchronous I/O capabilities* - ![HTTP/2](https://img.shields.io/badge/HTTP%2F2-✓-success) ![WebSocket](https://img.shields.io/badge/WebSocket-RFC%206455-success) ![SSL/TLS](https://img.shields.io/badge/SSL%2FTLS-OpenSSL-blue) ![Epoll](https://img.shields.io/badge/I%2FO-epoll-orange) +*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](#-features) • [Installation](#-installation) • [Configuration](#-configuration) • [Usage](#-usage) • [Contributing](#-contributing) • [License](#-license) +[Features](#-features) • [Installation](#-installation) • [Configuration](#-configuration) • [Usage](#-usage) • [Contributing](#-contributing) • [License](#-license) • [Documentation](DOCUMENTATION.md) @@ -50,6 +33,7 @@ Values can optionally be quoted with single or double quotes.svg)](https://www.l - [Roadmap](#-roadmap) - [Contributing](#-contributing) - [Security](#-security) +- [Documentation](DOCUMENTATION.md) - [License](#-license) - [Acknowledgments](#-acknowledgments) @@ -66,7 +50,7 @@ Carbon is a modern, production-ready HTTP/HTTPS server implementation in C, desi ## ✨ Features -### 🚀 Performance +### 🚀 High Performance - **Asynchronous I/O**: Epoll-based event handling for maximum efficiency - **Thread Pool**: Efficient connection handling with configurable worker threads - **Smart Caching**: File caching system to reduce disk I/O @@ -74,7 +58,7 @@ Carbon is a modern, production-ready HTTP/HTTPS server implementation in C, desi - **Keep-Alive Support**: Persistent connections to reduce overhead - **TCP Optimization**: Fine-tuned NODELAY and buffer configurations -### 🔒 Security +### 🔒 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 @@ -117,7 +101,7 @@ sudo apt-get install -y \ ## 🚀 Installation -### Quick Start +### Using HTTP configuration ```bash # Clone the repository @@ -131,21 +115,24 @@ sudo apt-get install -y build-essential libssl-dev libmagic-dev libnghttp2-dev # Build the server make -# Generate SSL certificates (for testing) +# Run the server +sudo ./server +``` +### Using SSL certificate or HTTPS, WebSocket, HTTP/2 +```bash +# Generate SSL certificates (optional) mkdir -p certs openssl req -x509 -nodes -days 365 -newkey rsa:4096 \ -keyout certs/key.pem -out certs/cert.pem \ -subj "/C=US/ST=State/L=City/O=Carbon/CN=localhost" -# Configure server (edit server.conf) -# Set: use_https = true, enable_http2 = true, enable_websocket = true - -# Run the server -sudo ./server # Test HTTP/2 curl --http2 -k https://localhost:443/ +# to use WebSocket (edit server.conf) +# Set: use_https = true, enable_http2 = true, enable_websocket = true + # Test WebSocket # Visit https://localhost:443/websocket-test.html in your browser ``` @@ -199,10 +186,10 @@ Create or edit `server.conf` in the project root. Carbon uses a traditional Linu # Lines starting with # are comments # Server listening port -port = 8080 +port = 443 # Enable HTTPS (requires valid certificates in certs/ directory) -use_https = false +use_https = true # Log file location log_file = log/server.log @@ -214,10 +201,16 @@ max_threads = 4 running = true # Server name or IP address (used for logging and response headers) -server_name = localhost +server_name = 10.0.0.206 # Enable verbose logging verbose = true + +# Enable HTTP/2 support (requires HTTPS) +enable_http2 = true + +# Enable WebSocket support +enable_websocket = false ``` **Configuration Options:** @@ -247,9 +240,6 @@ mkdir -p www/{css,js,images} # Create logs directory mkdir -p log - -# Place your web files in www/ -# Example: www/index.html, www/css/style.css, etc. ``` ## 🎯 Usage @@ -421,7 +411,6 @@ HTTP/2 provides significant performance improvements: - **Binary Protocol**: More efficient parsing - **Stream Prioritization**: Better resource loading -See [HTTP2_TESTING.md](HTTP2_TESTING.md) for detailed testing instructions. ## 📁 Project Structure @@ -445,10 +434,7 @@ Carbon/ │ └── key.pem ├── www/ # Web root directory │ ├── index.html -│ ├── websocket-test.html # WebSocket test client -│ ├── css/ -│ ├── js/ -│ └── images/ +│ └── websocket-test.html # WebSocket test client └── log/ # Log files └── server.log ``` @@ -460,7 +446,7 @@ Carbon/ | HTTP/2 Support | High | ✅ Implemented | | WebSocket Support | High | ✅ Implemented | | Secure WebSocket (wss://) | High | ✅ Implemented | -| API Rate Limiting | High | ✅ Implemented | +| API Rate Limiting | High | ⚠️ Broken (WIP) | | Security Headers | High | ✅ Implemented | | Memory Leak Prevention | High | ✅ Implemented | | User Authentication | High | 📋 Planned | @@ -499,19 +485,15 @@ Carbon implements multiple security layers, but for production deployments: **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](DOCUMENTATION.md) for more details. + ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. -## � Documentation - -- **[LETSENCRYPT_SETUP.md](LETSENCRYPT_SETUP.md)** - Complete guide for setting up Let's Encrypt SSL certificates -- **[SSL_FOR_IP_ADDRESS.md](SSL_FOR_IP_ADDRESS.md)** - SSL certificate options when using IP addresses -- **[SELF_SIGNED_CERTIFICATES.md](SELF_SIGNED_CERTIFICATES.md)** - Guide for generating and managing self-signed certificates -- **[HTTP2_TESTING.md](HTTP2_TESTING.md)** - HTTP/2 testing and verification guide -- **[check-http2.sh](check-http2.sh)** - Automated HTTP/2 diagnostic script - -## �🙏 Acknowledgments +## 🙏 Acknowledgments Carbon is built with these excellent open-source libraries: