📖 About

GSC-FQ is a high-performance proxy and stealth tunnel tool written in Rust, supporting forward proxy, reverse proxy, TCP/UDP traffic forwarding, and dual authentication based on Token and TOTP.

✨ Why GSC-FQ?

• ⚡ Extreme Performance: macOS 4.02x speedup, Linux splice() zero-copy, 84% memory optimization
• 🔒 Security Hardened: Token + TOTP dual authentication, Yamux multiplexing
• 🎯 Cross-Platform: Full support for Linux / macOS / Windows
• 🧪 High Quality: 91% E2E test coverage, SHA256 integrity verification
• 💡 Easy to Use: One-line install script, simple TOML configuration

🌟 Features

Service Types

Note: All configured services start automatically based on your config file. No need to specify modes.

Security Features

• 🔐 Dual Authentication: Token static key + TOTP dynamic verification (Google Authenticator)
• 🛡️ Connection Encryption: Yamux-based multiplexed encrypted tunnel
• ⚠️ Blackhole Mode: Active probing defense, confuse attackers

Performance Optimizations

• 🚀 Platform-Specific Optimizations:

  • macOS: 256KB buffer, 4.02x speedup (1MB scenario)
  • Linux: splice() zero-copy, +30% performance (real network)
  • Windows: 256KB optimized buffer, fixed performance issues

• 💾 Memory Optimization: Streaming processing, 1.63MB memory for 10MB transfer (-84%)

• 🎛️ Adaptive Transfer: Automatically select optimal strategy based on data size

📦 Installation

Option 1: Cargo (Recommended)

cargo install gsc-fq

Option 2: One-Line Install Script

curl -sSLf https://raw.githubusercontent.com/putao520/gsc-fq/main/install.sh | sh

Option 3: Docker

docker pull ghcr.io/putao520/gsc-fq:v0.9.2
docker run -v $(pwd)/config.toml:/app/config.toml ghcr.io/putao520/gsc-fq:v0.9.2

Option 4: Pre-built Binaries

Download pre-built binaries from GitHub Releases:

Linux (x86_64):

wget https://github.com/putao520/gsc-fq/releases/download/v0.9.2/gsc-fq-linux-x86_64.tar.gz
tar xzf gsc-fq-linux-x86_64.tar.gz
sudo mv gsc-fq /usr/local/bin/

Linux (aarch64):

wget https://github.com/putao520/gsc-fq/releases/download/v0.9.2/gsc-fq-linux-aarch64.tar.gz
tar xzf gsc-fq-linux-aarch64.tar.gz
sudo mv gsc-fq /usr/local/bin/

macOS (Intel):

wget https://github.com/putao520/gsc-fq/releases/download/v0.9.2/gsc-fq-macos-x86_64.tar.gz
tar xzf gsc-fq-macos-x86_64.tar.gz
sudo mv gsc-fq /usr/local/bin/

macOS (Apple Silicon):

wget https://github.com/putao520/gsc-fq/releases/download/v0.9.2/gsc-fq-macos-aarch64.tar.gz
tar xzf gsc-fq-macos-aarch64.tar.gz
sudo mv gsc-fq /usr/local/bin/

Windows (x86_64):

# Download from: https://github.com/putao520/gsc-fq/releases/download/v0.9.2/gsc-fq-windows-x86_64.zip
# Extract and add to PATH

Option 5: Build from Source

🚀 Quick Start

1️⃣ Forward Proxy

Scenario: Forward local port 8080 to remote API server

Configuration (config.toml):

[[proxies]]
local = "8080"
remote = "api.example.com:443"

Run:

gsc-fq
# Or specify config file
gsc-fq -c /path/to/config.toml

Test:

curl http://127.0.0.1:8080/api

2️⃣ Multiple Services (Recommended for Complex Scenarios)

Scenario: Run forward proxy and reverse proxy server simultaneously

Configuration (config.toml):

# Forward proxy rules
[[proxies]]
local = "8080"
remote = "api.example.com:443"

[[proxies]]
local = "3000"
remote = "db.example.com:5432"

# Reverse proxy server
[reverse_proxy_server]
port = 9001
allowed_tokens = ["my-secret-token"]

Run:

gsc-fq -c config.toml

What happens:

• ✅ Forward proxy on port 8080 → api.example.com:443
• ✅ Forward proxy on port 3000 → db.example.com:5432
• ✅ Reverse proxy server on port 9001
• All services start automatically based on config

3️⃣ Reverse Proxy

Scenario: Expose internal service to public internet via stealth tunnel

Server (Public machine config-server.toml):

[reverse_proxy_server]
port = 9001                    # Control connection port
allowed_tokens = ["my-secret-token"]

# Optional: Enable TOTP dynamic verification
totp_secret = "JBSWY3DPEHPK3PXP"  # Generate with `gsc-fq -g`

Client (Internal machine config-client.toml):

[reverse_proxy_client]
server = "PUBLIC_IP:9001"
token = "my-secret-token"

[[reverse_proxies]]
server_port = "443"            # Port exposed on public machine
local = "127.0.0.1:3000"       # Local service to expose

Run:

# Public machine
gsc-fq -c config-server.toml

# Internal machine
gsc-fq -c config-client.toml

Access: Visit PUBLIC_IP:443 to access the internal service

4️⃣ TOTP Dynamic Verification

Step 1: Generate TOTP secret

$ gsc-fq -g

✅ TOTP secret generated successfully!
📱 Secret: JBSWY3DPEHPK3PXP
🔐 Base32: JBSWY3DPEHPK3PXP

📷 Scan QR code with Google Authenticator:
████████████████████████
██ Scan this QR code to add  ██
████████████████████████

⏰ Verification code updates every 30 seconds

Step 2: Configure server to enable TOTP

[reverse_proxy_server]
port = 9001
totp_secret = "JBSWY3DPEHPK3PXP"  # Enter generated secret

Step 3: Client connects with TOTP verification code

# 6-digit code from Google Authenticator
gsc-fq -c config-client.toml

⚡ Performance Benchmarks

Platform Optimization Comparison

Benchmark environment: Apple M2, 16GB RAM, localhost loopback

Comparison with Other Solutions

High Concurrency Tests

📊 High concurrency stress test (200 concurrent connections)
  Successful connections: 200 / 200
  Failed connections: 0
  Total time: 156.23ms
  Average latency: 781μs
  Throughput: 1280.32 connections/sec

🛠️ Command Line Arguments

📋 Configuration Examples

Complete Configuration Example

# ==================== Forward Proxy ====================
# All configured services start automatically - no mode selection needed

[[proxies]]
local = "8080"
remote = "api.example.com:443"

[[proxies]]
local = "3000"
remote = "db.example.com:5432"

# ==================== Reverse Proxy Server ====================

[reverse_proxy_server]
port = 9001
allowed_tokens = ["token1", "token2"]

# TOTP configuration (optional)
totp_secret = "JBSWY3DPEHPK3PXP"

# Connection pool configuration
[connection_pool]
min_idle = 5
max_size = 100
idle_timeout = 300

# ==================== Reverse Proxy Client ====================

[reverse_proxy_client]
server = "PUBLIC_IP:9001"
token = "token1"

# Expose multiple local services
[[reverse_proxies]]
server_port = "443"        # HTTPS
local = "127.0.0.1:443"

[[reverse_proxies]]
server_port = "80"         # HTTP
local = "127.0.0.1:8080"

[[reverse_proxies]]
server_port = "22"         # SSH
local = "127.0.0.1:22"

# ==================== UDP Forwarding ====================

[[udp_proxies]]
local = "127.0.0.1:53"
remote = "8.8.8.8:53"

# ==================== Logging Configuration ====================

[logging]
level = "info"              # debug, info, warn, error
file = "/var/log/gsc-fq.log"
max_size = "100MB"
max_backups = 7

Important: All services in the config file will start automatically. You can mix and match any combination:

• [[proxies]] - Forward proxy rules
• [reverse_proxy_server] - Reverse proxy server
• [reverse_proxy_client] - Reverse proxy client
• [[udp_proxies]] - UDP forwarding

🎯 Use Cases

Use Case 1: Development Environment Proxy

Problem: Local development needs access to remote API with network restrictions

Solution:

# Configure forward proxy
[[proxies]]
local = "8080"
remote = "api.internal.com:443"

# Access
curl http://127.0.0.1:8080/api/users

Use Case 2: Remote Work

Problem: Home computer needs access to company internal services

Solution:

# Company server (public IP)
[reverse_proxy_server]
port = 9001
totp_secret = "xxx"

# Home computer
[reverse_proxy_client]
server = "COMPANY_PUBLIC_IP:9001"

[[reverse_proxies]]
server_port = "8080"
local = "127.0.0.1:80"  # Company internal OA system

Use Case 3: Game Acceleration

Problem: UDP game packets unstable

Solution:

[[udp_proxies]]
local = "127.0.0.1:25565"
remote = "game-server.com:25565"

🧪 Test Coverage

E2E Test Statistics

Running Tests

# Run all tests
cargo test

# Run E2E tests
cargo test --test network_resilience_test
cargo test --test high_concurrency_stress_test
cargo test --test edge_cases_test
cargo test --test data_forwarding_validation_test

📚 Architecture

Performance Optimization Architecture

┌─────────────────────────────────────────────┐
│      Platform-Specific Optimization Layer   │
├──────────┬──────────┬──────────┬──────────┤
│  macOS   │  Linux   │ Windows  │  Generic  │
│ 256KB    │ splice() │ 256KB    │ 256KB    │
│ bulk_copy│ zero-copy│ bulk_copy│ bulk_copy│
└──────────┴──────────┴──────────┴──────────┘
           ↓
┌─────────────────────────────────────────────┐
│         Adaptive Transfer Strategy          │
├──────────┬──────────┬──────────┬──────────┤
│ Small    │ Medium   │ Large    │ Stream   │
│ < 64KB   │ 64KB-1MB │ 1MB-10MB │ > 10MB   │
│ tokio    │ 128KB    │ 256KB    │ splice() │
└──────────┴──────────┴──────────┴──────────┘
           ↓
┌─────────────────────────────────────────────┐
│     Connection Management & Multiplexing    │
│     Yamux + Connection Pool + Blackhole    │
└─────────────────────────────────────────────┘

Core Modules

• adaptive_copy.rs: Known-size data adaptive transfer
• adaptive_stream.rs: Unknown-size streaming transfer
• splice_optimizer.rs: Linux splice() zero-copy optimizer
• zero_copy.rs: Platform-specific zero-copy implementation
• stealth_handler.rs: Stealth tunnel handling (blackhole mode)

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork this repository
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request

Development Requirements

• ✅ Code formatting: cargo fmt
• ✅ Code linting: cargo clippy
• ✅ Tests passing: cargo test
• ✅ Test coverage: > 80%

📊 Changelog

See CHANGELOG.md for detailed update history.

v0.9.2 (2026-01-12) - Latest

• ✅ Multiple Services: All services start automatically based on config file
• 🚀 Configuration-Driven: No need to specify modes, just configure what you need
• 🐛 Bug Fixes: Removed single-mode limitation

v0.9.0 (2026-01-12)

• 🚀 Performance: macOS 4.02x speedup, Linux splice() zero-copy
• 🧪 Testing: E2E coverage 48% → 91%
• 💾 Memory: 10MB transfer memory usage -84%
• 🐛 Bug Fixes: Resource leaks, TOTP compatibility

❓ FAQ

Q1: How to view logs?

A: Use debug mode or specify log file

# Debug mode
RUST_LOG=debug gsc-fq

# Specify log file
[logging]
level = "debug"
file = "/var/log/gsc-fq.log"

Q2: What if connection fails?

A: Check the following

1. Confirm Token and TOTP configuration is correct
2. Check firewall rules
3. View server/client logs
4. Verify network connectivity (ping, telnet)

Q3: How to improve performance?

A: Optimization suggestions

[connection_pool]
min_idle = 10        # Increase min idle connections
max_size = 200       # Increase connection pool size
idle_timeout = 600    # Extend idle timeout

Q4: Does it support Docker deployment?

A: Fully supported!

docker run -d \
  -v $(pwd)/config.toml:/app/config.toml \
  -p 8080:8080 \
  ghcr.io/putao520/gsc-fq:v0.9.2

⚖️ License

Dual-licensed under MIT or Apache-2.0.

🙏 Acknowledgments

• Tokio: Async runtime
• Yamux: Multiplexing
• Rust Crypto: Cryptographic algorithms