# bearice/redproxy-rs architecture

> Architecture diagram of the GitHub repository bearice/redproxy-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bearice/redproxy-rs
- Repository: https://github.com/bearice/redproxy-rs

## Overview

##### Project Type and Purpose
- This project is a high-performance proxy routing tool written in Rust. It is designed to translate protocols (e.g., HTTP CONNECT with mTLS, QUIC-based connections, SOCKS versions) and to enable policy-based selection of destination proxies.
- It also features an embedded web console, Prometheus metrics integration, access logs in JSON format, and supports dynamic reconfigurable rules via a RESTful API.

##### Analyzing the File Structure
- Top-level files (Cargo.toml, build.rs, config.yaml, etc.) and directories (.github, LICENSE, README.md) indicate standard Rust project conventions with CI/CD integration.
- There’s a “src” directory housing the primary application logic:
– Modules like “access_log.rs” and “metrics.rs” are dedicated to logging and monitoring.
– The “common” folder contains various networking utility modules (HTTP, QUIC, TLS, DNS, etc.), which are likely foundational libraries for protocol-specific handling.
– The “connectors” folder is segmented into different types (direct, HTTP, loadbalance, quic, socks), representing the code paths for outbound connections and protocol translation.
– The “listeners” folder includes files for handling incoming traffic (HTTP, QUIC, reverse proxy, socks, TPROXY), representing how the proxy receives requests.
– “rules” and “script” modules indicate policy configuration and scripting/extension support for dynamic decision-making.
- A separate “milu” directory exists that appears to function as a library or module (possibly for parsing and scripting) – with its own Cargo manifest and source files (parser, script, stdlib) – which likely provides the dynamic/scriptable policy engine embedded within the main system.
- The “ui” folder contains the web interface assets (HTML, JavaScript, CSS) for the embedded web console.

a. Main Components:
– Client Layer: External clients initiating connections using various protocols.
– Listener Modules: Distinct entry points for each protocol (HTTP CONNECT, QUIC, SOCKS, TPROXY, Reverse Proxy), represented by modules in “src/listeners/*”.
– Core Routing Engine: The heart of the proxy, processing incoming connections, maintaining context (see src/context.rs), and interfacing with rules and scripts.
– Connectors: Different outbound connection handlers (direct, HTTP, loadbalanced, etc. from “src/connectors/*”) that translate protocols or route traffic to the correct destination proxy.
– Policy Engine & Rules: Handling dynamic reconfiguration through RESTful API calls with business logic encapsulated in “src/rules” and “src/script”. The “milu” subproject with its parser and script features likely supports this layer.
– Monitoring and Logging: Access logs, Prometheus metrics (from “src/metrics.rs” and “src/access_log.rs”) for observability.
– Embedded Web Console & REST API: The UI directory provides a web-based interface, and REST endpoints likely exist within the main or configuration modules.
– External Dependencies: Any integrations with mTLS setups, Prometheus, or LDAP/other authentication methods visible in “src/common/auth.rs”.

b. Component Relationships and Data Flow:
– The client connects to one of the Listener modules.
– The Listener hands the request off to the Core Routing Engine.
– The Core Routing Engine interprets the connection using the policy/rules engine (which might dynamically load scripts via modules in “milu”) to decide which Connector to use.
– Data flows from the Connector outwards (or possibly vice versa, for reverse proxy scenarios).
– Observability data (logs, metrics) flow continuously to the monitoring components.
– External control is provided via the REST API and embedded web console, enabling live rule adjustments.
– Underpinning network commonalities are implemented in shared utility modules (“src/common/*”).

c. Architectural Patterns & Design Principles:
– Modular Design: Separation into listeners, connectors, and common utility modules.
– Extensibility: Use of a scripting/parser library (in the “milu” module) to achieve dynamic reconfigurability.
– Clean Separation of Concerns: Distinct components handling network I/O, business logic, configuration, and monitoring.
– Potential use of reactive or event-driven patterns to manage concurrent network connections.

d. Relevant Technologies & Frameworks:
– Rust as the primary programming language, emphasizing performance and safety.
– CI/CD integration via GitHub workflows.
– Prometheus for monitoring.
– Embedded web technologies for the UI (Vue.js is hinted by the inclusion of vue.global.prod.js).
– TLS/mTLS and QUIC protocols are supported, indicating reliance on modern networking libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    Client("Clients"):::client

    %% Listeners Subgraph
    subgraph "Listeners"
        L1("HTTP Listener"):::listener
        L2("QUIC Listener"):::listener
        L3("Reverse Proxy Listener"):::listener
        L4("Socks Listener"):::listener
        L5("TPROXY Listener"):::listener
    end

    %% Routing Engine Subgraph
    subgraph "Routing Engine"
        RE("Core Routing Engine"):::routing
    end

    %% Connectors Subgraph
    subgraph "Connectors"
        C1("Direct Connector"):::connector
        C2("HTTP Connector"):::connector
        C3("Loadbalance Connector"):::connector
        C4("QUIC Connector"):::connector
        C5("Socks Connector"):::connector
    end

    %% Policy Engine & Rules Subgraph
    subgraph "Policy Engine & Rules"
        P1("Filter Rules"):::policy
        P2("Script Extension"):::policy
        P3("Scripting Engine"):::policy
        subgraph "Milu Scripting"
            M1("Milu Library"):::policy
            M2("Milu Parser"):::policy
            M3("Milu Script"):::policy
        end
    end

    %% Observability Subgraph
    subgraph "Observability"
        O1("Access Logs"):::observability
        O2("Metrics"):::observability
    end

    %% UI / API Subgraph
    subgraph "UI / API"
        U1("Index Page"):::ui
        U2("App Script"):::ui
        U3("Vue Library"):::ui
        U4("Stylesheet"):::ui
    end

    %% Supporting Components Subgraph
    subgraph "Supporting"
        CUtil("Common Utilities"):::support
        Config("Configuration"):::support
    end

    %% Data Flow
    Client --> L1
    Client --> L2
    Client --> L3
    Client --> L4
    Client --> L5

    L1 --> RE
    L2 --> RE
    L3 --> RE
    L4 --> RE
    L5 --> RE

    RE --> C1
    RE --> C2
    RE --> C3
    RE --> C4
    RE --> C5

    RE --> P1
    RE --> P3

    U1 -->|"control"| RE

    RE --> O1
    RE --> O2

    RE -.-> CUtil
    RE -.-> Config

    %% Click Events for Listeners
    click L1 "https://github.com/bearice/redproxy-rs/blob/master/src/listeners/http.rs"
    click L2 "https://github.com/bearice/redproxy-rs/blob/master/src/listeners/quic.rs"
    click L3 "https://github.com/bearice/redproxy-rs/blob/master/src/listeners/reverse.rs"
    click L4 "https://github.com/bearice/redproxy-rs/blob/master/src/listeners/socks.rs"
    click L5 "https://github.com/bearice/redproxy-rs/blob/master/src/listeners/tproxy.rs"

    %% Click Events for Core Routing Engine
    click RE "https://github.com/bearice/redproxy-rs/blob/master/src/main.rs"
    click RE "https://github.com/bearice/redproxy-rs/blob/master/src/context.rs"

    %% Click Events for Connectors
    click C1 "https://github.com/bearice/redproxy-rs/blob/master/src/connectors/direct.rs"
    click C2 "https://github.com/bearice/redproxy-rs/blob/master/src/connectors/http.rs"
    click C3 "https://github.com/bearice/redproxy-rs/blob/master/src/connectors/loadbalance.rs"
    click C4 "https://github.com/bearice/redproxy-rs/blob/master/src/connectors/quic.rs"
    click C5 "https://github.com/bearice/redproxy-rs/blob/master/src/connectors/socks.rs"

    %% Click Events for Policy Engine & Rules
    click P1 "https://github.com/bearice/redproxy-rs/blob/master/src/rules/filter.rs"
    click P2 "https://github.com/bearice/redproxy-rs/blob/master/src/rules/script_ext.rs"
    click P3 "https://github.com/bearice/redproxy-rs/tree/master/src/script"
    click M1 "https://github.com/bearice/redproxy-rs/blob/master/milu/src/lib.rs"
    click M2 "https://github.com/bearice/redproxy-rs/blob/master/milu/src/parser.rs"
    click M3 "https://github.com/bearice/redproxy-rs/blob/master/milu/src/script.rs"

    %% Click Events for Observability
    click O1 "https://github.com/bearice/redproxy-rs/blob/master/src/access_log.rs"
    click O2 "https://github.com/bearice/redproxy-rs/blob/master/src/metrics.rs"

    %% Click Events for UI / API
    click U1 "https://github.com/bearice/redproxy-rs/blob/master/ui/index.html"
    click U2 "https://github.com/bearice/redproxy-rs/blob/master/ui/app.js"
    click U3 "https://github.com/bearice/redproxy-rs/blob/master/ui/lib/vue.global.prod.js"
    click U4 "https://github.com/bearice/redproxy-rs/blob/master/ui/style.css"

    %% Click Events for Supporting Components
    click CUtil "https://github.com/bearice/redproxy-rs/tree/master/src/common"
    click Config "https://github.com/bearice/redproxy-rs/blob/master/config.yaml"
    click Config "https://github.com/bearice/redproxy-rs/blob/master/src/config.rs"

    %% Style definitions
    classDef client fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef listener fill:#FF9933,stroke:#333,stroke-width:2px;
    classDef routing fill:#66FF66,stroke:#333,stroke-width:2px;
    classDef connector fill:#CC99FF,stroke:#333,stroke-width:2px;
    classDef policy fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef observability fill:#FF6666,stroke:#333,stroke-width:2px;
    classDef ui fill:#66CCFF,stroke:#333,stroke-width:2px;
    classDef support fill:#CCCCCC,stroke:#333,stroke-width:2px;
```
