Update README.md and add comprehensive documentation for Carbon HTTP Server
This commit is contained in:
931
DOCUMENTATION.md
Normal file
931
DOCUMENTATION.md
Normal file
@@ -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 = <number_of_cores * 2>
|
||||
|
||||
# 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 <pid>`
|
||||
|
||||
#### 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
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**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)
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user