Fixed: #2034

feat(proxy): centralize proxy handling with `proxyutil` package and enhance test coverage

- Added `proxyutil` package to simplify proxy handling across the codebase.
- Refactored various components (`executor`, `cliproxy`, `auth`, etc.) to use `proxyutil` for consistent and reusable proxy logic.
- Introduced support for "direct" proxy mode to explicitly bypass all proxies.
- Updated tests to validate proxy behavior (e.g., `direct`, HTTP/HTTPS, and SOCKS5).
- Enhanced YAML configuration documentation for proxy options.

sdk/cliproxy/rtprovider.go

@@ -1,16 +1,13 @@
 package cliproxy
 
 import (
-	"context"
-	"net"
 	"net/http"
-	"net/url"
 	"strings"
 	"sync"
 
 	coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/proxyutil"
 	log "github.com/sirupsen/logrus"
-	"golang.org/x/net/proxy"
 )
 
 // defaultRoundTripperProvider returns a per-auth HTTP RoundTripper based on
@@ -39,35 +36,12 @@ func (p *defaultRoundTripperProvider) RoundTripperFor(auth *coreauth.Auth) http.
 	if rt != nil {
 		return rt
 	}
-	// Parse the proxy URL to determine the scheme.
-	proxyURL, errParse := url.Parse(proxyStr)
-	if errParse != nil {
-		log.Errorf("parse proxy URL failed: %v", errParse)
+	transport, _, errBuild := proxyutil.BuildHTTPTransport(proxyStr)
+	if errBuild != nil {
+		log.Errorf("%v", errBuild)
 		return nil
 	}
-	var transport *http.Transport
-	// Handle different proxy schemes.
-	if proxyURL.Scheme == "socks5" {
-		// Configure SOCKS5 proxy with optional authentication.
-		username := proxyURL.User.Username()
-		password, _ := proxyURL.User.Password()
-		proxyAuth := &proxy.Auth{User: username, Password: password}
-		dialer, errSOCKS5 := proxy.SOCKS5("tcp", proxyURL.Host, proxyAuth, proxy.Direct)
-		if errSOCKS5 != nil {
-			log.Errorf("create SOCKS5 dialer failed: %v", errSOCKS5)
-			return nil
-		}
-		// Set up a custom transport using the SOCKS5 dialer.
-		transport = &http.Transport{
-			DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
-				return dialer.Dial(network, addr)
-			},
-		}
-	} else if proxyURL.Scheme == "http" || proxyURL.Scheme == "https" {
-		// Configure HTTP or HTTPS proxy.
-		transport = &http.Transport{Proxy: http.ProxyURL(proxyURL)}
-	} else {
-		log.Errorf("unsupported proxy scheme: %s", proxyURL.Scheme)
+	if transport == nil {
 		return nil
 	}
 	p.mu.Lock()

sdk/cliproxy/rtprovider_test.go

@@ -0,0 +1,22 @@
+package cliproxy
+
+import (
+	"net/http"
+	"testing"
+
+	coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
+)
+
+func TestRoundTripperForDirectBypassesProxy(t *testing.T) {
+	t.Parallel()
+
+	provider := newDefaultRoundTripperProvider()
+	rt := provider.RoundTripperFor(&coreauth.Auth{ProxyURL: "direct"})
+	transport, ok := rt.(*http.Transport)
+	if !ok {
+		t.Fatalf("transport type = %T, want *http.Transport", rt)
+	}
+	if transport.Proxy != nil {
+		t.Fatal("expected direct transport to disable proxy function")
+	}
+}

sdk/proxyutil/proxy.go

@@ -0,0 +1,139 @@
+package proxyutil
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"golang.org/x/net/proxy"
+)
+
+// Mode describes how a proxy setting should be interpreted.
+type Mode int
+
+const (
+	// ModeInherit means no explicit proxy behavior was configured.
+	ModeInherit Mode = iota
+	// ModeDirect means outbound requests must bypass proxies explicitly.
+	ModeDirect
+	// ModeProxy means a concrete proxy URL was configured.
+	ModeProxy
+	// ModeInvalid means the proxy setting is present but malformed or unsupported.
+	ModeInvalid
+)
+
+// Setting is the normalized interpretation of a proxy configuration value.
+type Setting struct {
+	Raw  string
+	Mode Mode
+	URL  *url.URL
+}
+
+// Parse normalizes a proxy configuration value into inherit, direct, or proxy modes.
+func Parse(raw string) (Setting, error) {
+	trimmed := strings.TrimSpace(raw)
+	setting := Setting{Raw: trimmed}
+
+	if trimmed == "" {
+		setting.Mode = ModeInherit
+		return setting, nil
+	}
+
+	if strings.EqualFold(trimmed, "direct") || strings.EqualFold(trimmed, "none") {
+		setting.Mode = ModeDirect
+		return setting, nil
+	}
+
+	parsedURL, errParse := url.Parse(trimmed)
+	if errParse != nil {
+		setting.Mode = ModeInvalid
+		return setting, fmt.Errorf("parse proxy URL failed: %w", errParse)
+	}
+	if parsedURL.Scheme == "" || parsedURL.Host == "" {
+		setting.Mode = ModeInvalid
+		return setting, fmt.Errorf("proxy URL missing scheme/host")
+	}
+
+	switch parsedURL.Scheme {
+	case "socks5", "http", "https":
+		setting.Mode = ModeProxy
+		setting.URL = parsedURL
+		return setting, nil
+	default:
+		setting.Mode = ModeInvalid
+		return setting, fmt.Errorf("unsupported proxy scheme: %s", parsedURL.Scheme)
+	}
+}
+
+// NewDirectTransport returns a transport that bypasses environment proxies.
+func NewDirectTransport() *http.Transport {
+	if transport, ok := http.DefaultTransport.(*http.Transport); ok && transport != nil {
+		clone := transport.Clone()
+		clone.Proxy = nil
+		return clone
+	}
+	return &http.Transport{Proxy: nil}
+}
+
+// BuildHTTPTransport constructs an HTTP transport for the provided proxy setting.
+func BuildHTTPTransport(raw string) (*http.Transport, Mode, error) {
+	setting, errParse := Parse(raw)
+	if errParse != nil {
+		return nil, setting.Mode, errParse
+	}
+
+	switch setting.Mode {
+	case ModeInherit:
+		return nil, setting.Mode, nil
+	case ModeDirect:
+		return NewDirectTransport(), setting.Mode, nil
+	case ModeProxy:
+		if setting.URL.Scheme == "socks5" {
+			var proxyAuth *proxy.Auth
+			if setting.URL.User != nil {
+				username := setting.URL.User.Username()
+				password, _ := setting.URL.User.Password()
+				proxyAuth = &proxy.Auth{User: username, Password: password}
+			}
+			dialer, errSOCKS5 := proxy.SOCKS5("tcp", setting.URL.Host, proxyAuth, proxy.Direct)
+			if errSOCKS5 != nil {
+				return nil, setting.Mode, fmt.Errorf("create SOCKS5 dialer failed: %w", errSOCKS5)
+			}
+			return &http.Transport{
+				Proxy: nil,
+				DialContext: func(_ context.Context, network, addr string) (net.Conn, error) {
+					return dialer.Dial(network, addr)
+				},
+			}, setting.Mode, nil
+		}
+		return &http.Transport{Proxy: http.ProxyURL(setting.URL)}, setting.Mode, nil
+	default:
+		return nil, setting.Mode, nil
+	}
+}
+
+// BuildDialer constructs a proxy dialer for settings that operate at the connection layer.
+func BuildDialer(raw string) (proxy.Dialer, Mode, error) {
+	setting, errParse := Parse(raw)
+	if errParse != nil {
+		return nil, setting.Mode, errParse
+	}
+
+	switch setting.Mode {
+	case ModeInherit:
+		return nil, setting.Mode, nil
+	case ModeDirect:
+		return proxy.Direct, setting.Mode, nil
+	case ModeProxy:
+		dialer, errDialer := proxy.FromURL(setting.URL, proxy.Direct)
+		if errDialer != nil {
+			return nil, setting.Mode, fmt.Errorf("create proxy dialer failed: %w", errDialer)
+		}
+		return dialer, setting.Mode, nil
+	default:
+		return nil, setting.Mode, nil
+	}
+}

sdk/proxyutil/proxy_test.go

@@ -0,0 +1,89 @@
+package proxyutil
+
+import (
+	"net/http"
+	"testing"
+)
+
+func TestParse(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		input   string
+		want    Mode
+		wantErr bool
+	}{
+		{name: "inherit", input: "", want: ModeInherit},
+		{name: "direct", input: "direct", want: ModeDirect},
+		{name: "none", input: "none", want: ModeDirect},
+		{name: "http", input: "http://proxy.example.com:8080", want: ModeProxy},
+		{name: "https", input: "https://proxy.example.com:8443", want: ModeProxy},
+		{name: "socks5", input: "socks5://proxy.example.com:1080", want: ModeProxy},
+		{name: "invalid", input: "bad-value", want: ModeInvalid, wantErr: true},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			setting, errParse := Parse(tt.input)
+			if tt.wantErr && errParse == nil {
+				t.Fatal("expected error, got nil")
+			}
+			if !tt.wantErr && errParse != nil {
+				t.Fatalf("unexpected error: %v", errParse)
+			}
+			if setting.Mode != tt.want {
+				t.Fatalf("mode = %d, want %d", setting.Mode, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildHTTPTransportDirectBypassesProxy(t *testing.T) {
+	t.Parallel()
+
+	transport, mode, errBuild := BuildHTTPTransport("direct")
+	if errBuild != nil {
+		t.Fatalf("BuildHTTPTransport returned error: %v", errBuild)
+	}
+	if mode != ModeDirect {
+		t.Fatalf("mode = %d, want %d", mode, ModeDirect)
+	}
+	if transport == nil {
+		t.Fatal("expected transport, got nil")
+	}
+	if transport.Proxy != nil {
+		t.Fatal("expected direct transport to disable proxy function")
+	}
+}
+
+func TestBuildHTTPTransportHTTPProxy(t *testing.T) {
+	t.Parallel()
+
+	transport, mode, errBuild := BuildHTTPTransport("http://proxy.example.com:8080")
+	if errBuild != nil {
+		t.Fatalf("BuildHTTPTransport returned error: %v", errBuild)
+	}
+	if mode != ModeProxy {
+		t.Fatalf("mode = %d, want %d", mode, ModeProxy)
+	}
+	if transport == nil {
+		t.Fatal("expected transport, got nil")
+	}
+
+	req, errRequest := http.NewRequest(http.MethodGet, "https://example.com", nil)
+	if errRequest != nil {
+		t.Fatalf("http.NewRequest returned error: %v", errRequest)
+	}
+
+	proxyURL, errProxy := transport.Proxy(req)
+	if errProxy != nil {
+		t.Fatalf("transport.Proxy returned error: %v", errProxy)
+	}
+	if proxyURL == nil || proxyURL.String() != "http://proxy.example.com:8080" {
+		t.Fatalf("proxy URL = %v, want http://proxy.example.com:8080", proxyURL)
+	}
+}