Sing-Proxy: A Robust Go Proxy Client Library

Features

Installation

go get github.com/SyNdicateFoundation/singproxy

-tags=with_utls,with_gvisor,with_quic,with_dhcp,with_acme,with_clash_api,with_wireguard

Basic Usage

package main
import (
	"context"
	"fmt"
	"io"
	"net"
	"net/http"
	"time"
	"github.com/SyNdicateFoundation/singproxy"
)
func main() {
	// Example VLESS URL with a REALITY configuration and a name in the fragment.
	proxyURL := "vless://a-uuid@example.com:443?security=reality&sni=sni.example.com&fp=chrome&pbk=YOUR_REALITY_KEY&sid=abcdef1234#MyVlessProxy"
	timeout := 8 * time.Second
	// 1. Parse the URL using the factory function.
	proxy, err := singproxy.FromURL(timeout, proxyURL)
	if err != nil {
		panic(fmt.Sprintf("Failed to parse proxy URL: %v", err))
	}
	// The String() method returns the cleaned name from the URL fragment.
	fmt.Printf("Successfully parsed proxy: %s\n", proxy.String()) // Prints "vless://a-uuid@example.com:443?security=reality&sni=sni.example.com&fp=chrome&pbk=YOUR_REALITY_KEY&sid=abcdef1234"
	// 2. Create an HTTP client that uses the proxy's custom dialer.
	httpClient := &http.Client{
		Timeout: 15 * time.Second,
		Transport: &http.Transport{
			DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
				tcpAddr, err := net.ResolveTCPAddr(network, addr)
				if err != nil {
					return nil, err
				}
				// Use the proxy's DialContext method to establish the connection.
				return proxy.DialContext(ctx, network, tcpAddr)
			},
		},
	}
	// 3. Make a request to a test endpoint through the proxy.
	fmt.Println("Making request to httpbin.org/get...")
	resp, err := httpClient.Get("https://httpbin.org/get")
	if err != nil {
		panic(fmt.Sprintf("Request failed through proxy: %v", err))
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Printf("Status: %s\n", resp.Status)
	fmt.Printf("Response Body (first 100 bytes): %.100s...\n", string(body))
}

Example: A Simple Concurrent Proxy Tester

package main
import (
	"context"
	"fmt"
	"io"
	"net"
	"net/http"
	"sync"
	"time"
	"github.com/SyNdicateFoundation/singproxy"
)
// TestResult holds the outcome of a single proxy test.
type TestResult struct {
	ProxyName string
	Latency time.Duration
	Success bool
	Error error
}
func main() {
	proxyURLs := []string{
		"direct", // A direct connection for baseline comparison.
		"vless://a-uuid@example.com:443?security=tls&sni=example.com#VLESS-Example",
		"ss://YWVzLTI1Ni1nY206cGFzc3dvcmQ=@example.com:8080#Shadowsocks-Example",
		"trojan://password@example.com:443?sni=example.com#Trojan-Example",
		"this-is-an-invalid-url", // An invalid URL to show error handling.
		"hysteria2://-->invalid-user@example.com:4567#Malformed-Hysteria2", // Will be cleaned and parsed.
	}
	fmt.Printf("Parsing %d proxy URLs...\n", len(proxyURLs))
	timeout := 8 * time.Second
	// Use FromURLs to parse all proxies concurrently. It returns valid proxies and any errors.
	proxies, errs := singproxy.FromURLs(timeout, proxyURLs...)
	// Print any parsing errors encountered.
	if len(errs) > 0 {
		fmt.Printf("\nEncountered %d parsing errors:\n", len(errs))
		for _, err := range errs {
			fmt.Printf(" - %v\n", err)
		}
	}
	fmt.Printf("\nSuccessfully parsed %d proxies. Starting connection tests...\n\n", len(proxies))
	var wg sync.WaitGroup
	results := make(chan TestResult, len(proxies))
	// Test each valid proxy in its own goroutine.
	for _, p := range proxies {
		wg.Add(1)
		go testProxy(p, results, &wg)
	}
	// Wait for all tests to complete.
	wg.Wait()
	close(results)
	// Print the collected results.
	for result := range results {
		if result.Success {
			fmt.Printf("[SUCCESS] Proxy: %-30s | Latency: %s\n", result.ProxyName, result.Latency)
		} else {
			fmt.Printf("[FAILURE] Proxy: %-30s | Error: %v\n", result.ProxyName, result.Error)
		}
	}
}
// testProxy attempts to make an HTTP GET request through the given proxy and sends the result to a channel.
func testProxy(p singproxy.Proxy, results chan<- TestResult, wg *sync.WaitGroup) {
	defer wg.Done()
	result := TestResult{ProxyName: p.String()}
	startTime := time.Now()
	httpClient := &http.Client{
		Timeout: 10 * time.Second, // Timeout for the entire HTTP request.
		Transport: &http.Transport{
			// Use the proxy's custom dialer.
			DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
				tcpAddr, err := net.ResolveTCPAddr(network, addr)
				if err != nil {
					return nil, err
				}
				return p.DialContext(ctx, network, tcpAddr)
			},
			// Disable keep-alives for more accurate, isolated latency measurement.
			DisableKeepAlives: true,
		},
	}
	// Make the test request.
	resp, err := httpClient.Get("https://httpbin.org/get")
	if err != nil {
		result.Success = false
		result.Error = err
		results <- result
		return
	}
	defer resp.Body.Close()
	if resp.StatusCode == http.StatusOK {
		result.Success = true
		result.Latency = time.Since(startTime)
		// Drain the body to properly measure the time for the full response.
		_, _ = io.Copy(io.Discard, resp.Body)
	} else {
		result.Success = false
		result.Error = fmt.Errorf("bad status: %s", resp.Status)
	}
	results <- result
}

How The Robust Parsing Works

Supported Protocols

License

Credits