chore: refactored the implementation of suduko mux (#2486)

Author: saba-futai

adapter/outbound/sudoku.go

@@ -19,6 +19,9 @@ type Sudoku struct {
 	option   *SudokuOption
 	baseConf sudoku.ProtocolConfig
 
+	httpMaskMu     sync.Mutex
+	httpMaskClient *sudoku.HTTPMaskTunnelClient
+
 	muxMu           sync.Mutex
 	muxClient       *sudoku.MultiplexClient
 	muxBackoffUntil time.Time
@@ -40,7 +43,7 @@ type SudokuOption struct {
 	HTTPMaskMode       string   `proxy:"http-mask-mode,omitempty"`      // "legacy" (default), "stream", "poll", "auto"
 	HTTPMaskTLS        bool     `proxy:"http-mask-tls,omitempty"`       // only for http-mask-mode stream/poll/auto
 	HTTPMaskHost       string   `proxy:"http-mask-host,omitempty"`      // optional Host/SNI override (domain or domain:port)
-	HTTPMaskMultiplex  string   `proxy:"http-mask-multiplex,omitempty"` // "off" (default), "auto", "on"
+	HTTPMaskMultiplex  string   `proxy:"http-mask-multiplex,omitempty"` // "off" (default), "auto" (reuse h1/h2), "on" (single tunnel, multi-target)
 	CustomTable        string   `proxy:"custom-table,omitempty"`        // optional custom byte layout, e.g. xpxvvpvv
 	CustomTables       []string `proxy:"custom-tables,omitempty"`       // optional table rotation patterns, overrides custom-table when non-empty
 }
@@ -53,18 +56,12 @@ func (s *Sudoku) DialContext(ctx context.Context, metadata *C.Metadata) (_ C.Con
 	}
 
 	muxMode := normalizeHTTPMaskMultiplex(cfg.HTTPMaskMultiplex)
-	if !cfg.DisableHTTPMask && muxMode != "off" {
-		shouldTry := muxMode == "on" || (muxMode == "auto" && httpTunnelModeEnabled(cfg.HTTPMaskMode))
-		if shouldTry {
-			stream, muxErr := s.dialMultiplex(ctx, cfg.TargetAddress, muxMode)
-			if muxErr == nil {
-				return NewConn(stream, s), nil
-			}
-			if muxMode != "auto" {
-				return nil, muxErr
-			}
-			s.noteMuxFailure(muxMode, muxErr)
+	if muxMode == "on" && !cfg.DisableHTTPMask && httpTunnelModeEnabled(cfg.HTTPMaskMode) {
+		stream, muxErr := s.dialMultiplex(ctx, cfg.TargetAddress, muxMode)
+		if muxErr == nil {
+			return NewConn(stream, s), nil
 		}
+		return nil, muxErr
 	}
 
 	c, err := s.dialAndHandshake(ctx, cfg)
@@ -229,6 +226,7 @@ func NewSudoku(option SudokuOption) (*Sudoku, error) {
 
 func (s *Sudoku) Close() error {
 	s.resetMuxClient()
+	s.resetHTTPMaskClient()
 	return s.Base.Close()
 }
 
@@ -261,7 +259,17 @@ func (s *Sudoku) dialAndHandshake(ctx context.Context, cfg *sudoku.ProtocolConfi
 
 	var c net.Conn
 	if !cfg.DisableHTTPMask && httpTunnelModeEnabled(cfg.HTTPMaskMode) {
-		c, err = sudoku.DialHTTPMaskTunnel(ctx, cfg.ServerAddress, cfg, s.dialer.DialContext)
+		muxMode := normalizeHTTPMaskMultiplex(cfg.HTTPMaskMultiplex)
+		switch muxMode {
+		case "auto", "on":
+			client, errX := s.getOrCreateHTTPMaskClient(cfg)
+			if errX != nil {
+				return nil, errX
+			}
+			c, err = client.Dial(ctx)
+		default:
+			c, err = sudoku.DialHTTPMaskTunnel(ctx, cfg.ServerAddress, cfg, s.dialer.DialContext)
+		}
 	}
 	if c == nil && err == nil {
 		c, err = s.dialer.DialContext(ctx, "tcp", s.addr)
@@ -380,3 +388,35 @@ func (s *Sudoku) resetMuxClient() {
 		s.muxClient = nil
 	}
 }
+
+func (s *Sudoku) getOrCreateHTTPMaskClient(cfg *sudoku.ProtocolConfig) (*sudoku.HTTPMaskTunnelClient, error) {
+	if s == nil {
+		return nil, fmt.Errorf("nil adapter")
+	}
+	if cfg == nil {
+		return nil, fmt.Errorf("config is required")
+	}
+
+	s.httpMaskMu.Lock()
+	defer s.httpMaskMu.Unlock()
+
+	if s.httpMaskClient != nil {
+		return s.httpMaskClient, nil
+	}
+
+	c, err := sudoku.NewHTTPMaskTunnelClient(cfg.ServerAddress, cfg, s.dialer.DialContext)
+	if err != nil {
+		return nil, err
+	}
+	s.httpMaskClient = c
+	return c, nil
+}
+
+func (s *Sudoku) resetHTTPMaskClient() {
+	s.httpMaskMu.Lock()
+	defer s.httpMaskMu.Unlock()
+	if s.httpMaskClient != nil {
+		s.httpMaskClient.CloseIdleConnections()
+		s.httpMaskClient = nil
+	}
+}

docs/config.yaml

@@ -1068,7 +1068,7 @@ proxies: # socks5
     # http-mask-mode: legacy # 可选：legacy（默认）、stream、poll、auto；stream/poll/auto 支持走 CDN/反代
     # http-mask-tls: true # 可选：仅在 http-mask-mode 为 stream/poll/auto 时生效；true 强制 https；false 强制 http（不会根据端口自动推断）
     # http-mask-host: "" # 可选：覆盖 Host/SNI（支持 example.com 或 example.com:443）；仅在 http-mask-mode 为 stream/poll/auto 时生效
-    # http-mask-multiplex: off # 可选：off（默认）、auto、on；复用单条隧道并在其内多路复用多个目标连接
+    # http-mask-multiplex: off # 可选：off（默认）、auto（复用 h1.1 keep-alive / h2 连接，减少每次建链 RTT）、on（单条隧道内多路复用多个目标连接；仅在 http-mask-mode=stream/poll/auto 生效）
     enable-pure-downlink: false # 是否启用混淆下行，false的情况下能在保证数据安全的前提下极大提升下行速度，与服务端端保持相同(如果此处为false，则要求aead不可为none)
 
   # anytls

transport/sudoku/config.go

@@ -58,9 +58,10 @@ type ProtocolConfig struct {
 	// HTTPMaskHost optionally overrides the HTTP Host header / SNI host for HTTP tunnel modes (client-side).
 	HTTPMaskHost string
 
-	// HTTPMaskMultiplex controls whether the client reuses a single (HTTP-masked) tunnel connection and
-	// opens multiple logical target streams inside it (reduces RTT for subsequent connections).
-	// Values: "off" / "auto" / "on".
+	// HTTPMaskMultiplex controls multiplex behavior when HTTPMask tunnel modes are enabled:
+	//   - "off": disable reuse; each Dial establishes its own HTTPMask tunnel
+	//   - "auto": reuse underlying HTTP connections across multiple tunnel dials (HTTP/1.1 keep-alive / HTTP/2)
+	//   - "on": enable "single tunnel, multi-target" mux (Sudoku-level multiplex; Dial behaves like "auto" otherwise)
 	HTTPMaskMultiplex string
 }
 

transport/sudoku/httpmask_tunnel.go

@@ -83,6 +83,59 @@ func DialHTTPMaskTunnel(ctx context.Context, serverAddress string, cfg *Protocol
 		Mode:         cfg.HTTPMaskMode,
 		TLSEnabled:   cfg.HTTPMaskTLSEnabled,
 		HostOverride: cfg.HTTPMaskHost,
+		Multiplex:    cfg.HTTPMaskMultiplex,
 		DialContext:  dial,
 	})
 }
+
+type HTTPMaskTunnelClient struct {
+	mode   string
+	client *httpmask.TunnelClient
+}
+
+func NewHTTPMaskTunnelClient(serverAddress string, cfg *ProtocolConfig, dial TunnelDialer) (*HTTPMaskTunnelClient, error) {
+	if cfg == nil {
+		return nil, fmt.Errorf("config is required")
+	}
+	if cfg.DisableHTTPMask {
+		return nil, fmt.Errorf("http mask is disabled")
+	}
+	switch strings.ToLower(strings.TrimSpace(cfg.HTTPMaskMode)) {
+	case "stream", "poll", "auto":
+	default:
+		return nil, fmt.Errorf("http-mask-mode=%q does not use http tunnel", cfg.HTTPMaskMode)
+	}
+	switch strings.ToLower(strings.TrimSpace(cfg.HTTPMaskMultiplex)) {
+	case "auto", "on":
+	default:
+		return nil, fmt.Errorf("http-mask-multiplex=%q does not enable reuse", cfg.HTTPMaskMultiplex)
+	}
+
+	c, err := httpmask.NewTunnelClient(serverAddress, httpmask.TunnelClientOptions{
+		TLSEnabled:   cfg.HTTPMaskTLSEnabled,
+		HostOverride: cfg.HTTPMaskHost,
+		DialContext:  dial,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return &HTTPMaskTunnelClient{
+		mode:   cfg.HTTPMaskMode,
+		client: c,
+	}, nil
+}
+
+func (c *HTTPMaskTunnelClient) Dial(ctx context.Context) (net.Conn, error) {
+	if c == nil || c.client == nil {
+		return nil, fmt.Errorf("nil httpmask tunnel client")
+	}
+	return c.client.DialTunnel(ctx, c.mode)
+}
+
+func (c *HTTPMaskTunnelClient) CloseIdleConnections() {
+	if c == nil || c.client == nil {
+		return
+	}
+	c.client.CloseIdleConnections()
+}

transport/sudoku/multiplex.go

@@ -1,11 +1,11 @@
 package sudoku
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"net"
 	"strings"
-	"time"
 
 	"github.com/metacubex/mihomo/transport/sudoku/multiplex"
 )
@@ -46,26 +46,19 @@ func (c *MultiplexClient) Dial(ctx context.Context, targetAddress string) (net.C
 		return nil, fmt.Errorf("target address cannot be empty")
 	}
 
-	stream, err := c.sess.OpenStream()
+	addrBuf, err := EncodeAddress(targetAddress)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("encode target address failed: %w", err)
 	}
 
-	if deadline, ok := ctx.Deadline(); ok {
-		_ = stream.SetWriteDeadline(deadline)
-		defer stream.SetWriteDeadline(time.Time{})
+	if ctx != nil && ctx.Err() != nil {
+		return nil, ctx.Err()
 	}
 
-	addrBuf, err := EncodeAddress(targetAddress)
+	stream, err := c.sess.OpenStream(addrBuf)
 	if err != nil {
-		_ = stream.Close()
-		return nil, fmt.Errorf("encode target address failed: %w", err)
-	}
-	if _, err := stream.Write(addrBuf); err != nil {
-		_ = stream.Close()
-		return nil, fmt.Errorf("send target address failed: %w", err)
+		return nil, err
 	}
-
 	return stream, nil
 }
 
@@ -114,18 +107,21 @@ func (s *MultiplexServer) AcceptStream() (net.Conn, error) {
 	if s == nil || s.sess == nil {
 		return nil, fmt.Errorf("nil session")
 	}
-	return s.sess.AcceptStream()
+	c, _, err := s.sess.AcceptStream()
+	return c, err
 }
 
-// AcceptTCP accepts a multiplex stream and reads the target address preface, returning the stream positioned at
-// application data.
+// AcceptTCP accepts a multiplex stream and returns the target address declared in the open frame.
 func (s *MultiplexServer) AcceptTCP() (net.Conn, string, error) {
-	stream, err := s.AcceptStream()
+	if s == nil || s.sess == nil {
+		return nil, "", fmt.Errorf("nil session")
+	}
+	stream, payload, err := s.sess.AcceptStream()
 	if err != nil {
 		return nil, "", err
 	}
 
-	target, err := DecodeAddress(stream)
+	target, err := DecodeAddress(bytes.NewReader(payload))
 	if err != nil {
 		_ = stream.Close()
 		return nil, "", err
@@ -147,4 +143,3 @@ func (s *MultiplexServer) IsClosed() bool {
 	}
 	return s.sess.IsClosed()
 }
-

transport/sudoku/multiplex/mux.go

@@ -0,0 +1,39 @@
+package multiplex
+
+import (
+	"fmt"
+	"io"
+)
+
+const (
+	// MagicByte marks a Sudoku tunnel connection that will switch into multiplex mode.
+	// It is sent after the Sudoku handshake + downlink mode byte.
+	//
+	// Keep it distinct from UoTMagicByte and address type bytes.
+	MagicByte byte = 0xED
+	Version   byte = 0x01
+)
+
+func WritePreface(w io.Writer) error {
+	if w == nil {
+		return fmt.Errorf("nil writer")
+	}
+	_, err := w.Write([]byte{MagicByte, Version})
+	return err
+}
+
+func ReadVersion(r io.Reader) (byte, error) {
+	var b [1]byte
+	if _, err := io.ReadFull(r, b[:]); err != nil {
+		return 0, err
+	}
+	return b[0], nil
+}
+
+func ValidateVersion(v byte) error {
+	if v != Version {
+		return fmt.Errorf("unsupported multiplex version: %d", v)
+	}
+	return nil
+}
+