Code Structure#

Cheolsu Proxy is structured as a Rust-based monorepo with a Tauri desktop application.

Overall Structure#

Workspace Structure#

Root Cargo.toml#

[workspace]
members = [
    "proxyapi",
    "proxyapi_v2",
    "proxyapi_models",
    "tauri-ui/src-tauri"
]

[workspace.dependencies]
# Common dependency definitions

External Crates#

proxy_v2_models is not a workspace member but is a separate crate that other workspace members reference as a dependency.

Backend Structure#

1. proxyapi_v2/ (Main Proxy Engine)#

2. certificate_authority/ (CA Management)#

Module Structure#

// mod.rs
pub trait CertificateAuthority {
    fn generate_certificate(&self, domain: &str) -> Result<Certificate, Error>;
    fn gen_pkcs12_identity(&self, domain: &str) -> Result<Identity, Error>;
}

pub struct RcgenAuthority { /* ... */ }
pub struct OpensslAuthority { /* ... */ }

Key Features#

• Dynamic Certificate Generation: Automatic certificate generation per domain
• PKCS12 Support: PKCS12 certificate generation for native-tls
• Cross-platform: Support for macOS, Windows

3. proxy/ (Proxy Core)#

Builder Pattern#

// builder.rs
pub struct ProxyBuilder {
    listen_addr: SocketAddr,
    ca: Box<dyn CertificateAuthority>,
    tls_handler: Box<dyn TlsHandler>,
}

impl ProxyBuilder {
    pub fn new() -> Self { /* ... */ }
    pub fn listen_addr(mut self, addr: SocketAddr) -> Self { /* ... */ }
    pub fn certificate_authority(mut self, ca: Box<dyn CertificateAuthority>) -> Self { /* ... */ }
    pub fn build(self) -> Result<Proxy, Error> { /* ... */ }
}

Internal Logic#

// internal.rs
pub struct Proxy {
    listener: TcpListener,
    ca: Box<dyn CertificateAuthority>,
    tls_handler: Box<dyn TlsHandler>,
}

impl Proxy {
    pub async fn run(&self) -> Result<(), Error> { /* ... */ }
    async fn handle_connection(&self, stream: TcpStream) -> Result<(), Error> { /* ... */ }
    async fn handle_http(&self, stream: TcpStream) -> Result<(), Error> { /* ... */ }
    async fn handle_https(&self, stream: TcpStream) -> Result<(), Error> { /* ... */ }
}

Frontend Structure (tauri-ui/)#

FSD (Feature-Sliced Design) Architecture#

Layer Responsibilities#

1. app/ (Application Layer)#

• App.tsx: Root component, routing setup
• layouts/: Common layout components
• providers/: React Context providers

2. pages/ (Page Layer)#

• network-dashboard/: Main network monitoring page
• sessions/: Session management page

3. widgets/ (Widget Layer)#

• network-table/: Network request table
• network-header/: Network header information
• host-path-tree/: Host-based path tree

4. features/ (Feature Layer)#

• network-table/: Table-related features (filtering, sorting, etc.)
• transaction-details/: Transaction detail view
• websocket-test/: WebSocket test functionality

5. entities/ (Entity Layer)#

• proxy/: Proxy-related data models
• session/: Session-related data models
• transaction/: Transaction-related data models

6. shared/ (Shared Layer)#

• api/: Backend API client
• ui/: Reusable UI components
• lib/: Utility functions
• stores/: Zustand state management
• assets/: Static assets

Tauri Backend (tauri-ui/src-tauri/)#

Tauri Configuration#

// tauri.conf.json
{
  "build": {
    "beforeDevCommand": "pnpm run dev",
    "beforeBuildCommand": "pnpm run build",
    "devPath": "http://localhost:1420",
    "distDir": "../dist"
  },
  "package": {
    "productName": "Cheolsu Proxy",
    "version": "0.1.0"
  }
}

Data Flow#

1. Proxy Request Processing#

sequenceDiagram
    participant Client as Client
    participant Proxy as Proxy Server
    participant CA as CA Manager
    participant Target as Target Server

    Client->>Proxy: HTTP/HTTPS Request
    Proxy->>Proxy: Request Analysis
    alt HTTPS Request
        Proxy->>CA: Certificate Request
        CA-->>Proxy: Dynamic Certificate
        Proxy->>Client: TLS Handshake
    end
    Proxy->>Target: Forward Request
    Target-->>Proxy: Response
    Proxy-->>Client: Forward Response

2. Frontend Data Flow#

graph TD
    A[Tauri Backend] --> B[Tauri Invoke API]
    B --> C[React Components]

State Management#

Zustand Store Structure#

// stores/proxy-store.ts
interface ProxyStore {
  // State
  isRunning: boolean;
  listenAddr: string;
  requests: Transaction[];

  // Actions
  startProxy: () => void;
  stopProxy: () => void;
  addRequest: (request: Transaction) => void;
  clearRequests: () => void;
}

// stores/session-store.ts
interface SessionStore {
  // State
  sessions: Session[];
  activeSession: string | null;

  // Actions
  createSession: () => void;
  switchSession: (id: string) => void;
  deleteSession: (id: string) => void;
}

API Communication#

Tauri Invoke API#

// shared/api/proxy.ts
import { invoke } from "@tauri-apps/api/core";

export async function fetchProxyStatus(): Promise<boolean> {
  return await invoke("proxy_status");
}

export async function startProxy(address: string): Promise<void> {
  return await invoke("start_proxy", { addr: address });
}

export async function stopProxy(): Promise<void> {
  return await invoke("stop_proxy");
}

// New proxy functions using proxyapi_v2
export interface ProxyStartResult {
  status: boolean;
  message: string;
}

export async function startProxyV2(
  port: number = 8100
): Promise<ProxyStartResult> {
  return invoke("start_proxy_v2", { addr: `127.0.0.1:${port}` });
}

export async function stopProxyV2(): Promise<void> {
  return invoke("stop_proxy_v2");
}

export async function getProxyV2Status(): Promise<boolean> {
  return invoke("proxy_v2_status");
}

Test Structure#

Rust Tests#

Frontend Tests#

Build and Deployment#

Development Build#

# Backend build
cargo build

# Frontend build
cd tauri-ui && pnpm run build

# Tauri app build
cd tauri-ui && pnpm run tauri build

Production Build#

# Release build
cargo build --release

# Tauri app packaging
cd tauri-ui && pnpm run tauri build -- --target universal-apple-darwin

Performance Optimization#

Backend Optimization#

• Asynchronous Processing: Using tokio runtime
• Memory Pooling: Object pool pattern implementation
• Streaming: Large data streaming processing

Frontend Optimization#

• Virtualization: Large list virtualization
• Memoization: React.memo, useMemo usage
• Code Splitting: Dynamic import usage

Security Considerations#

Backend Security#

• Certificate Management: Secure CA certificate generation
• Memory Security: Safe memory management
• Input Validation: All input data validation

Frontend Security#

• XSS Prevention: Input data escaping
• CSRF Prevention: Token-based authentication
• Content Security Policy: CSP header settings

Extensibility#

Plugin System (Future)#

// Plugin trait
pub trait Plugin {
    fn name(&self) -> &str;
    fn version(&self) -> &str;
    fn handle_request(&self, request: &mut Request) -> Result<(), Error>;
    fn handle_response(&self, response: &mut Response) -> Result<(), Error>;
}

API Extension#

• REST API addition
• GraphQL support
• gRPC support

Understanding this structure will help you effectively navigate and contribute to the Cheolsu Proxy codebase.