Subconvergo

A high-performance Go reimplementation of subconverter using mihomo for automatic proxy protocol support.

Module: github.com/gfunc/subconvergo

Status: Production-ready for Clash format. Other formats are functional but less thoroughly tested.

---

🚀 Quick Start

# Clone and build
git clone https://github.com/gfunc/subconvergo.git
cd subconvergo
make build

# Run server
./subconvergo
# Server starts on http://localhost:25500

# Test it
curl http://localhost:25500/version

---

✨ Features

• 13 Proxy Protocols: SS, SSR, VMess, VLESS, Trojan, Hysteria, Hysteria2, TUIC, AnyTLS, Snell, WireGuard, SOCKS5, HTTP
• High Performance: Sub-25µs parsing, comprehensive test coverage
• Auto Protocol Updates: New protocols supported via mihomo upgrades
• Full Compatibility: Same API and config format as C++ version
• Production Ready: 50+ tests, comprehensive benchmarks, Docker support
• Extensible: Fallback architecture for future protocols
• Caching System: File-based caching with TTL and stale-while-revalidate support
• Improved Observability: Parser, handler, and generator log contextual info/errors to simplify troubleshooting

---

📚 Documentation

• Configuration Reference - Complete config options, filtering, protocols
• API Reference - Endpoints, parameters, supported formats
• Development Guide - Building, testing, architecture, workflow
• Smoke Tests - Detailed guide to the integration test suite
• Feature Parity - Comparison with C++ subconverter

---

⚠️ Behavioral Differences

While Subconvergo aims for full compatibility with the C++ version, there are some intentional differences:

1. Clash Source Format: By default, Subconvergo ignores the proxy-groups and rules defined in the source subscription (including Clash configs) to provide a clean slate for the target configuration. This aligns with the C++ version's behavior. You can override this by setting ignore_source=false in the request parameters.
2. Deduplication: Subconvergo automatically deduplicates proxies and proxy groups to ensure valid configuration output. Duplicate names are suffixed (e.g., Proxy_1).
3. Protocol Parsing: Subconvergo uses mihomo adapters for parsing, which may have stricter or slightly different validation logic compared to the custom parsers in the C++ version.
4. Local File URI: Subconvergo supports file:// URIs for subscription sources
5. Clash Relay Groups: Subconvergo automatically converts deprecated relay proxy groups into a chain of dialer-proxy configurations using proxy-providers when generating Clash configs. This ensures compatibility with modern Clash/Mihomo versions that have removed relay support.

---

🧪 Testing

Coverage: See make coverage for per-package numbers | Status: ✅ All Passing

Quick Test

# Unit tests (fast, no Docker)
make test-unit

# Smoke tests (integration/API with Docker)
make test

See Smoke Tests for details on the integration test suite and parity verification.

---

🛠️ Development

Prerequisites

• Go 1.25+
• Docker (for smoke tests)
• Python 3.8+ (for smoke tests)

Build & Run

# Install dependencies
go mod download

# Build
make build

# Development mode (auto-reload)
make dev

---

🔄 Migration from C++ Version

This Go implementation is a drop-in replacement for most use cases.

✅ Compatible

• Same base/ directory structure
• Same configuration format (pref.ini/yml/toml)
• Core API endpoints (/sub, /version, /readconf, /getprofile, /getruleset, /render)
• All proxy protocols (SS, SSR, VMess, Trojan, VLESS, Hysteria, Hysteria2, TUIC, AnyTLS, Snell, WireGuard, etc.)

⚠️ Not Implemented

• list parameter (Node List/Proxy Provider output)
• filename parameter
• QuickJS filter/sort script execution

📖 Complete Feature Parity Status

---

🤝 Contributing

Contributions welcome! Please ensure:

1. ✅ Unit tests pass: make test-unit
2. ✅ Smoke tests pass: make test
3. ✅ Code formatted: make fmt

📖 Development Guide

---

License

MIT License - See LICENSE file

---

🙏 Acknowledgments

• mihomo - Proxy protocol support
• subconverter - Original implementation