ss-proxy

A high-performance proxy server built with Rust, supporting HTTP/HTTPS and WebSocket protocol forwarding, with SQLite database for session and downstream server management.

English | 简体中文

• ss-proxy
  • System Requirements
  • Features
  • Quick Start
    • 1. Clone the Repository
    • 2. Initialize Database
    • 3. Add Test Session
    • 4. Start Proxy Server
    • 5. Test Proxy
  • Quick Examples
    • HTTP Proxy
    • WebSocket Proxy
  • Routing Rules
  • Error Handling
  • Development Guide
    • Common Commands
    • Running Tests
  • Documentation

System Requirements

• Rust: 1.90.0+ (Edition 2024 support)
• SQLite: 3.x
• OS: Linux / macOS / Windows

Note: The project uses rust-toolchain.toml to automatically manage the Rust version. When you first clone the project, rustup will automatically download and install Rust 1.90.0.

Features

• 🚀 High-Performance Async Proxy: Built on Tokio and Axum
• 🔄 Protocol Support: HTTP/HTTPS and WebSocket proxying
• 🌊 Streaming: Native support for streaming responses (SSE, LLM API, chunked encoding)
• 💾 Session Management: SQLite database for session storage
• 🎯 Dynamic Routing: Route to different downstream servers based on session_id
• ⚡ Connection Pooling: Built-in database and HTTP client connection pools
• 📊 Health Checks: Downstream server status validation

Quick Start

1. Clone the Repository

git clone https://github.com/second-state/ss-proxy.git
cd ss-proxy

After entering the project directory, rustup will automatically install Rust 1.90.0 (if not already installed).

2. Initialize Database

# Add execute permission and run
chmod +x init_db.sh
./init_db.sh

This will create the ./sessions.db database file. For database structure and detailed operations, see Database Guide.

3. Add Test Session

sqlite3 sessions.db <<EOF
INSERT INTO sessions (session_id, downstream_server_url, downstream_server_status)
VALUES ('session_001', 'https://httpbin.org', 'active');
EOF

4. Start Proxy Server

# Use default configuration (0.0.0.0:8080)
cargo run --release

# Or customize port
cargo run --release -- --port 9090

For more configuration options, see Configuration Guide.

5. Test Proxy

# Test HTTP proxy
curl http://localhost:8080/session_001/get

# Test health check
curl http://localhost:8080/health

Quick Examples

HTTP Proxy

curl http://localhost:8080/session_001/get

WebSocket Proxy

wscat -c ws://localhost:8080/ws/session_001

💡 Tip: Want complete end-to-end examples? Check out the Complete Tutorial Examples with detailed steps and multiple test scenarios.

💡 Tip: For more examples (POST requests, streaming, query parameters, etc.), see Routing Rules Guide.

Routing Rules

ss-proxy supports HTTP/HTTPS and WebSocket proxying with different forwarding behaviors:

• HTTP/HTTPS: session_id is only used to query the database and does not appear in the downstream URL
• WebSocket: session_id is appended to the downstream WebSocket URL path

For detailed routing rules, forwarding behavior, and examples, see Routing Rules Guide.

Error Handling

HTTP Status Code	Description
200-5xx	Original response from downstream server
404	session_id does not exist
503	Downstream server unavailable (status not active)
502	Cannot connect to downstream server

Development Guide

Common Commands

# Release build (optimized)
cargo build --release

# Run project
cargo run --release

Running Tests

# Run all tests (recommended)
./run_tests.sh

# Run unit tests only
cargo test

# Run integration tests only
cargo test --test integration

For detailed testing guide, see Testing Documentation.

Documentation

• � Complete Tutorial Examples - End-to-end examples and test scenarios
• �📖 Database Guide - Database structure and operations
• ⚙️ Configuration Guide - Configuration options and deployment
• 🧪 Testing Guide - Test suite and CI/CD workflows
• 🔀 Routing Rules Guide - Routing rules and request forwarding behavior