Pristine Software Design

High-Performance Reverse Proxy Architecture & Component Design

System Architecture Overview

High-Level Architecture

Loading diagram...

Core Component Architecture

Main Components

ReverseProxy

• Main orchestrator and entry point
• Manages HTTP/HTTPS servers
• Handles SSL context setup
• Coordinates component lifecycle

RequestRouter

• Domain-based request routing
• Backend server selection
• TLS requirement determination
• WebSocket capability detection

ConnectionHandler

• Individual connection management
• Request/response forwarding
• Protocol upgrade handling
• Error response generation

C++ Class Structure

// Core Classes
class ReverseProxy {
private:
    boost::asio::io_context io_context_;
    tcp::acceptor http_acceptor_;
    tcp::acceptor https_acceptor_;
    ssl::context ssl_context_;
    
public:
    bool initialize(const std::string& configPath);
    void run();
    void stop();
};

class RequestRouter {
private:
    std::shared_ptr<ConfigManager> config_manager_;
    
public:
    std::pair<std::string, int> getBackendForDomain(
        const std::string& domain) const;
    bool isWebSocketEnabled(const std::string& domain) const;
    bool requiresTLS(const std::string& domain) const;
};

class ConnectionHandler {
private:
    tcp::socket socket_;
    ssl::stream<tcp::socket> ssl_socket_;
    beast::flat_buffer buffer_;
    http::request<http::dynamic_body> request_;
    
public:
    void start();
    void handle_request();
    void forward_to_backend();
};

Protocol Handling & Communication

Multi-Protocol Support

HTTP/1.1

• Full request/response proxying
• Header preservation
• Keep-alive support
• Chunked transfer encoding

HTTP/2

• Stream multiplexing
• Header compression (HPACK)
• Server push capability
• Binary framing protocol

WebSocket

• Protocol upgrade handling
• Bidirectional communication
• Frame-based messaging
• Connection persistence

Request Processing Flow

Loading diagram...

Configuration & Certificate Management

Configuration Architecture

YAML Configuration

• Human-readable format
• Hierarchical structure
• Site-specific settings
• Global proxy configuration

Dynamic Loading

• Runtime configuration parsing
• Validation and error handling
• Singleton pattern implementation
• Thread-safe access

Certificate Management System

// Certificate Management
class CertificateManager {
private:
    std::string cert_dir_;
    std::string email_;
    std::string acme_server_;
    
public:
    bool ensure_certificate(const std::string& domain);
    CertificateInfo get_certificate_info(const std::string& domain) const;
    void setup_ssl_context(ssl::context& ctx, const std::string& domain);
    void check_renewals();
    
private:
    bool request_certificate_acme(const std::string& domain);
    bool generate_self_signed(const std::string& domain);
    bool certificate_exists(const std::string& domain) const;
    bool is_certificate_valid(const std::string& domain) const;
};

struct CertificateInfo {
    std::string domain;
    std::string cert_path;
    std::string key_path;
    std::chrono::system_clock::time_point expiry;
    bool is_self_signed;
    bool is_valid;
};

// Configuration Structures
struct SiteConfig {
    std::string domain;
    std::string backend;
    std::string tls;  // "auto", "manual", "off"
    bool websocket;
    int timeout_seconds;
};

struct ProxyConfig {
    int http_port;
    int https_port;
    std::string email;
    std::string cert_dir;
    std::string acme_server;
    int timeout_seconds;
    int max_connections;
    std::vector<SiteConfig> sites;
};

Asynchronous I/O & Performance Design

Boost.Asio Integration

Event Loop

• Single-threaded event loop
• Non-blocking I/O operations
• Callback-based async handling
• Efficient resource utilization

Connection Management

• Async accept operations
• Connection pooling
• Graceful connection handling
• Resource cleanup

Performance Optimizations

// Async Operation Patterns
void ConnectionHandler::start() {
    do_read();
}

void ConnectionHandler::do_read() {
    auto self = shared_from_this();
    http::async_read(socket_, buffer_, request_,
        [self](beast::error_code ec, std::size_t bytes) {
            self->on_read(ec, bytes);
        });
}

void ConnectionHandler::on_read(beast::error_code ec, 
                               std::size_t bytes_transferred) {
    if (!ec) {
        handle_request();
    } else {
        close_connection();
    }
}

// Backend Connection Pool
class BackendPool {
private:
    std::queue<std::shared_ptr<tcp::socket>> available_connections_;
    std::mutex pool_mutex_;
    
public:
    std::shared_ptr<tcp::socket> get_connection(
        const std::string& host, int port);
    void return_connection(std::shared_ptr<tcp::socket> conn);
};

SSL/TLS & Security Architecture

TLS Implementation

Certificate Types

• Self-signed certificates
• Let's Encrypt ACME protocol
• Manual certificate installation
• Automatic renewal system

Security Features

• TLS 1.2+ support
• Strong cipher suites
• Perfect forward secrecy
• Certificate validation

ACME Protocol Implementation

// ACME Certificate Request Flow
bool CertificateManager::request_certificate_acme(const std::string& domain) {
    // 1. Create account with ACME server
    auto account_key = generate_account_key();
    auto account_url = register_account(account_key, email_);
    
    // 2. Create order for domain
    auto order_url = create_order(account_url, domain);
    
    // 3. Get authorization challenges
    auto challenges = get_challenges(order_url);
    
    // 4. Complete HTTP-01 challenge
    for (const auto& challenge : challenges) {
        if (challenge.type == "http-01") {
            setup_challenge_response(challenge);
            notify_challenge_ready(challenge.url);
            wait_for_validation(challenge.url);
        }
    }
    
    // 5. Generate CSR and finalize order
    auto csr = generate_csr(domain);
    finalize_order(order_url, csr);
    
    // 6. Download certificate
    auto cert_url = get_certificate_url(order_url);
    auto certificate = download_certificate(cert_url);
    
    // 7. Save certificate and key
    save_certificate(domain, certificate);
    return true;
}

Error Handling & Monitoring Design

Error Handling Strategy

Connection Errors

• Backend connection failures
• Timeout handling
• Graceful degradation
• Client error responses

Certificate Errors

• Certificate validation failures
• ACME challenge failures
• Automatic fallback to self-signed
• Renewal error handling

Logging & Monitoring

// Logging Infrastructure
enum class LogLevel {
    DEBUG,
    INFO,
    WARNING,
    ERROR,
    CRITICAL
};

class Logger {
public:
    static void log(LogLevel level, const std::string& message);
    static void log_request(const std::string& method, 
                           const std::string& path,
                           const std::string& host,
                           int status_code,
                           std::chrono::milliseconds duration);
    static void log_error(const std::string& component,
                         const std::string& error,
                         const std::string& context);
};

// Metrics Collection
struct ProxyMetrics {
    std::atomic<uint64_t> total_requests{0};
    std::atomic<uint64_t> successful_requests{0};
    std::atomic<uint64_t> failed_requests{0};
    std::atomic<uint64_t> active_connections{0};
    std::atomic<uint64_t> bytes_transferred{0};
    
    std::chrono::steady_clock::time_point start_time;
    std::map<std::string, uint64_t> domain_requests;
    std::map<int, uint64_t> status_codes;
};

← Back to Pristine Project