feat(sub): full XHTTP field mapping for Clash/Mihomo subscriptions (#5417)

* feat(sub): add full XHTTP field mapping for Clash subscriptions The Clash subscription generator only emitted path, host, mode in xhttp-opts. Mihomo supports all XHTTP parameters including padding, xmux (reuse-settings), session/seq placement, and more. Add buildXhttpClashOpts() that maps all client-relevant XHTTP fields from 3x-ui's camelCase JSON storage to Mihomo's kebab-case YAML format using an explicit allowlist approach. Field mapping (source-verified against Mihomo adapter/outbound/vless.go): - String fields: xPaddingBytes→x-padding-bytes, sessionPlacement→ session-placement, etc. (10 fields with DPI default filtering) - Bool fields: noGRPCHeader→no-grpc-header, xPaddingObfsMode→ x-padding-obfs-mode (with gated sub-fields) - Nested: xmux→reuse-settings (6 sub-fields with kebab-case) - Headers: pass through with Host key dropped - Server-only fields automatically excluded (not in allowlist) DPI defaults filtered: scMaxEachPostBytes="1000000", scMinPostsIntervalMs="30" (known DPI fingerprint) * test(sub): add comprehensive tests for buildXhttpClashOpts 9 test functions covering all field mapping categories: - FullFieldMapping: every kebab-case key verified - DPIDefaultsFiltered: scMaxEachPostBytes=1000000 and scMinPostsIntervalMs=30 - PaddingObfsGate: false/absent/true-with-no-gated-fields - XmuxMapsToReuseSettings: full mapping, empty, int/float64/zero hKeepAlivePeriod - ServerOnlyFieldsExcluded: noSSEHeader, scMaxBufferedPosts, etc. - NilInput and EmptyInput: return nil - HostFallbackFromHeaders: headers.Host, only-Host, case-insensitive drop - NoGRPCHeaderFalsey: false and absent both produce no key * fix(sub): clean up redundant skipValue check and add missing xhttp no-settings test - In buildXhttpClashOpts, change string-field loop condition so that skipValue == "" means "no filter" rather than redundantly comparing v against "" twice (xPaddingBytes was the affected entry) - Add TestApplyTransport_XHTTP_NoSettings to pin the behaviour when xhttpSettings is absent: applyTransport returns true, network is set to "xhttp", and xhttp-opts is not emitted
2026-08-15 07:40:59 +00:00 · 2026-06-21 03:32:13 +05:00
parent 29b14dac59
commit 1a4aef3353
2 changed files with 594 additions and 19 deletions
@@ -145,6 +145,22 @@ func TestApplyTransport_XHTTP_HostFromHeaders(t *testing.T) {
 	}
 }

+func TestApplyTransport_XHTTP_NoSettings(t *testing.T) {
+	svc := &SubClashService{}
+	proxy := map[string]any{}
+	stream := map[string]any{}
+
+	if !svc.applyTransport(proxy, "xhttp", stream) {
+		t.Fatalf("applyTransport returned false for xhttp with no xhttpSettings")
+	}
+	if proxy["network"] != "xhttp" {
+		t.Fatalf("network = %v, want xhttp", proxy["network"])
+	}
+	if _, exists := proxy["xhttp-opts"]; exists {
+		t.Fatalf("xhttp-opts should be absent when xhttpSettings is missing, got %#v", proxy["xhttp-opts"])
+	}
+}
+
 func TestApplyTransport_HTTPUpgrade(t *testing.T) {
 	svc := &SubClashService{}
 	proxy := map[string]any{}
@@ -301,3 +317,457 @@ func TestBuildProxy_VLESSNoneEncryptionOmittedForClash(t *testing.T) {
 		t.Fatalf("uuid = %v, want %v", proxy["uuid"], client.ID)
 	}
 }
+
+func TestBuildXhttpClashOpts_FullFieldMapping(t *testing.T) {
+	xhttp := map[string]any{
+		"path":    "/api/v1",
+		"mode":    "stream-up",
+		"host":    "example.com",
+		"xPaddingBytes":    "100-1000",
+		"xPaddingObfsMode": true,
+		"xPaddingKey":       "mykey",
+		"xPaddingHeader":    "X-Trace-ID",
+		"xPaddingPlacement": "queryInHeader",
+		"xPaddingMethod":    "tokenish",
+		"uplinkHTTPMethod":  "POST",
+		"sessionPlacement":  "query",
+		"sessionKey":        "sess",
+		"seqPlacement":      "header",
+		"seqKey":            "seq",
+		"uplinkDataPlacement": "body",
+		"uplinkDataKey":      "udata",
+		"uplinkChunkSize":    "64-256",
+		"noGRPCHeader":       true,
+		"scMaxEachPostBytes": "500000",
+		"scMinPostsIntervalMs": "50",
+		"xmux": map[string]any{
+			"maxConcurrency":   "16-32",
+			"maxConnections":   "4",
+			"cMaxReuseTimes":   "8",
+			"hMaxRequestTimes":  "600-900",
+			"hMaxReusableSecs":  "1800-3000",
+			"hKeepAlivePeriod":  float64(60),
+		},
+		"headers": map[string]any{
+			"User-Agent": "chrome",
+			"Host":       "should-be-dropped.com",
+		},
+	}
+
+	opts := buildXhttpClashOpts(xhttp)
+	if opts == nil {
+		t.Fatal("expected non-nil opts for full field mapping")
+	}
+
+	// Direct fields
+	if opts["path"] != "/api/v1" {
+		t.Errorf("path = %v, want /api/v1", opts["path"])
+	}
+	if opts["mode"] != "stream-up" {
+		t.Errorf("mode = %v, want stream-up", opts["mode"])
+	}
+	if opts["host"] != "example.com" {
+		t.Errorf("host = %v, want example.com", opts["host"])
+	}
+
+	// String fields
+	if opts["x-padding-bytes"] != "100-1000" {
+		t.Errorf("x-padding-bytes = %v", opts["x-padding-bytes"])
+	}
+	if opts["uplink-http-method"] != "POST" {
+		t.Errorf("uplink-http-method = %v", opts["uplink-http-method"])
+	}
+	if opts["session-placement"] != "query" {
+		t.Errorf("session-placement = %v", opts["session-placement"])
+	}
+	if opts["session-key"] != "sess" {
+		t.Errorf("session-key = %v", opts["session-key"])
+	}
+	if opts["seq-placement"] != "header" {
+		t.Errorf("seq-placement = %v", opts["seq-placement"])
+	}
+	if opts["seq-key"] != "seq" {
+		t.Errorf("seq-key = %v", opts["seq-key"])
+	}
+	if opts["uplink-data-placement"] != "body" {
+		t.Errorf("uplink-data-placement = %v", opts["uplink-data-placement"])
+	}
+	if opts["uplink-data-key"] != "udata" {
+		t.Errorf("uplink-data-key = %v", opts["uplink-data-key"])
+	}
+
+	// DPI-filtered fields (non-default values should pass)
+	if opts["sc-max-each-post-bytes"] != "500000" {
+		t.Errorf("sc-max-each-post-bytes = %v", opts["sc-max-each-post-bytes"])
+	}
+	if opts["sc-min-posts-interval-ms"] != "50" {
+		t.Errorf("sc-min-posts-interval-ms = %v", opts["sc-min-posts-interval-ms"])
+	}
+
+	// Bool fields
+	if opts["no-grpc-header"] != true {
+		t.Errorf("no-grpc-header = %v, want true", opts["no-grpc-header"])
+	}
+	if opts["x-padding-obfs-mode"] != true {
+		t.Errorf("x-padding-obfs-mode = %v, want true", opts["x-padding-obfs-mode"])
+	}
+
+	// Padding obfs gated fields
+	if opts["x-padding-key"] != "mykey" {
+		t.Errorf("x-padding-key = %v", opts["x-padding-key"])
+	}
+	if opts["x-padding-header"] != "X-Trace-ID" {
+		t.Errorf("x-padding-header = %v", opts["x-padding-header"])
+	}
+	if opts["x-padding-placement"] != "queryInHeader" {
+		t.Errorf("x-padding-placement = %v", opts["x-padding-placement"])
+	}
+	if opts["x-padding-method"] != "tokenish" {
+		t.Errorf("x-padding-method = %v", opts["x-padding-method"])
+	}
+
+	// Non-zero value fields
+	if opts["uplink-chunk-size"] != "64-256" {
+		t.Errorf("uplink-chunk-size = %v", opts["uplink-chunk-size"])
+	}
+
+	// Reuse-settings (xmux)
+	reuse, ok := opts["reuse-settings"].(map[string]any)
+	if !ok {
+		t.Fatalf("reuse-settings missing or wrong type: %#v", opts["reuse-settings"])
+	}
+	if reuse["max-concurrency"] != "16-32" {
+		t.Errorf("max-concurrency = %v", reuse["max-concurrency"])
+	}
+	if reuse["max-connections"] != "4" {
+		t.Errorf("max-connections = %v", reuse["max-connections"])
+	}
+	if reuse["c-max-reuse-times"] != "8" {
+		t.Errorf("c-max-reuse-times = %v", reuse["c-max-reuse-times"])
+	}
+	if reuse["h-max-request-times"] != "600-900" {
+		t.Errorf("h-max-request-times = %v", reuse["h-max-request-times"])
+	}
+	if reuse["h-max-reusable-secs"] != "1800-3000" {
+		t.Errorf("h-max-reusable-secs = %v", reuse["h-max-reusable-secs"])
+	}
+	if reuse["h-keep-alive-period"] != float64(60) {
+		t.Errorf("h-keep-alive-period = %v, want 60", reuse["h-keep-alive-period"])
+	}
+
+	// Headers (Host should be dropped)
+	headers, ok := opts["headers"].(map[string]any)
+	if !ok {
+		t.Fatalf("headers missing or wrong type: %#v", opts["headers"])
+	}
+	if headers["User-Agent"] != "chrome" {
+		t.Errorf("headers[User-Agent] = %v", headers["User-Agent"])
+	}
+	if _, has := headers["Host"]; has {
+		t.Error("headers should not contain Host key")
+	}
+	if _, has := headers["host"]; has {
+		t.Error("headers should not contain host key (case-insensitive)")
+	}
+}
+
+func TestBuildXhttpClashOpts_DPIDefaultsFiltered(t *testing.T) {
+	xhttp := map[string]any{
+		"path":                "/",
+		"mode":                "stream-up",
+		"scMaxEachPostBytes":   "1000000",
+		"scMinPostsIntervalMs": "30",
+	}
+	opts := buildXhttpClashOpts(xhttp)
+	if opts == nil {
+		t.Fatal("expected non-nil opts (path and mode should be present)")
+	}
+	if _, has := opts["sc-max-each-post-bytes"]; has {
+		t.Error("sc-max-each-post-bytes should be filtered when value is 1000000")
+	}
+	if _, has := opts["sc-min-posts-interval-ms"]; has {
+		t.Error("sc-min-posts-interval-ms should be filtered when value is 30")
+	}
+}
+
+func TestBuildXhttpClashOpts_PaddingObfsGate(t *testing.T) {
+	// Sub-test 1: obfs mode false — gated fields should not appear
+	t.Run("ObfsModeFalse", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path":            "/",
+			"xPaddingObfsMode": false,
+			"xPaddingKey":     "should-not-appear",
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		if _, has := opts["x-padding-obfs-mode"]; has {
+			t.Error("x-padding-obfs-mode should not appear when false")
+		}
+		if _, has := opts["x-padding-key"]; has {
+			t.Error("x-padding-key should not appear when obfs mode is false")
+		}
+	})
+
+	// Sub-test 2: obfs mode absent — gated fields should not appear
+	t.Run("ObfsModeAbsent", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path":        "/",
+			"xPaddingKey": "should-not-appear",
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		if _, has := opts["x-padding-key"]; has {
+			t.Error("x-padding-key should not appear when obfs mode is absent")
+		}
+	})
+
+	// Sub-test 3: obfs mode true with no gated fields — only x-padding-obfs-mode appears
+	t.Run("ObfsModeTrueNoGatedFields", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path":             "/",
+			"xPaddingObfsMode": true,
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		if opts["x-padding-obfs-mode"] != true {
+			t.Errorf("x-padding-obfs-mode = %v, want true", opts["x-padding-obfs-mode"])
+		}
+		if _, has := opts["x-padding-key"]; has {
+			t.Error("x-padding-key should not appear when not set")
+		}
+	})
+}
+
+func TestBuildXhttpClashOpts_XmuxMapsToReuseSettings(t *testing.T) {
+	// Sub-test 1: full xmux mapping
+	t.Run("FullXmux", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path": "/",
+			"xmux": map[string]any{
+				"maxConcurrency":   "16-32",
+				"maxConnections":   "4",
+				"cMaxReuseTimes":   "8",
+				"hMaxRequestTimes":  "600-900",
+				"hMaxReusableSecs":  "1800-3000",
+				"hKeepAlivePeriod":  float64(60),
+			},
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		reuse, ok := opts["reuse-settings"].(map[string]any)
+		if !ok {
+			t.Fatalf("reuse-settings missing or wrong type: %#v", opts["reuse-settings"])
+		}
+		if reuse["max-concurrency"] != "16-32" {
+			t.Errorf("max-concurrency = %v", reuse["max-concurrency"])
+		}
+		if reuse["max-connections"] != "4" {
+			t.Errorf("max-connections = %v", reuse["max-connections"])
+		}
+		if reuse["c-max-reuse-times"] != "8" {
+			t.Errorf("c-max-reuse-times = %v", reuse["c-max-reuse-times"])
+		}
+		if reuse["h-max-request-times"] != "600-900" {
+			t.Errorf("h-max-request-times = %v", reuse["h-max-request-times"])
+		}
+		if reuse["h-max-reusable-secs"] != "1800-3000" {
+			t.Errorf("h-max-reusable-secs = %v", reuse["h-max-reusable-secs"])
+		}
+		if reuse["h-keep-alive-period"] != float64(60) {
+			t.Errorf("h-keep-alive-period = %v, want 60", reuse["h-keep-alive-period"])
+		}
+	})
+
+	// Sub-test 2: empty xmux map — no reuse-settings key
+	t.Run("EmptyXmux", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path": "/",
+			"xmux": map[string]any{},
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts (path is present)")
+		}
+		if _, has := opts["reuse-settings"]; has {
+			t.Error("reuse-settings should not appear for empty xmux")
+		}
+	})
+
+	// Sub-test 3: hKeepAlivePeriod as int (not float64)
+	t.Run("IntKeepAlivePeriod", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path": "/",
+			"xmux": map[string]any{
+				"hKeepAlivePeriod": int(60),
+			},
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		reuse, ok := opts["reuse-settings"].(map[string]any)
+		if !ok {
+			t.Fatalf("reuse-settings missing: %#v", opts["reuse-settings"])
+		}
+		if reuse["h-keep-alive-period"] != int(60) {
+			t.Errorf("h-keep-alive-period = %v (%T), want 60 (int)", reuse["h-keep-alive-period"], reuse["h-keep-alive-period"])
+		}
+	})
+
+	// Sub-test 4: hKeepAlivePeriod=0 should be filtered
+	t.Run("ZeroKeepAlivePeriod", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path": "/",
+			"xmux": map[string]any{
+				"hKeepAlivePeriod": float64(0),
+			},
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		if _, has := opts["reuse-settings"]; has {
+			t.Error("reuse-settings should not appear when only hKeepAlivePeriod=0")
+		}
+	})
+}
+
+func TestBuildXhttpClashOpts_ServerOnlyFieldsExcluded(t *testing.T) {
+	xhttp := map[string]any{
+		"path":                 "/",
+		"noSSEHeader":          true,
+		"scMaxBufferedPosts":   "100",
+		"scStreamUpServerSecs": "5",
+		"serverMaxHeaderBytes": "4096",
+	}
+	opts := buildXhttpClashOpts(xhttp)
+	if opts == nil {
+		t.Fatal("expected non-nil opts (path is present)")
+	}
+	if _, has := opts["no-sse-header"]; has {
+		t.Error("noSSEHeader should not appear in Clash output (server-only)")
+	}
+	if _, has := opts["sc-max-buffered-posts"]; has {
+		t.Error("scMaxBufferedPosts should not appear in Clash output (server-only)")
+	}
+	if _, has := opts["sc-stream-up-server-secs"]; has {
+		t.Error("scStreamUpServerSecs should not appear in Clash output (server-only)")
+	}
+	if _, has := opts["server-max-header-bytes"]; has {
+		t.Error("serverMaxHeaderBytes should not appear in Clash output (not in Mihomo)")
+	}
+}
+
+func TestBuildXhttpClashOpts_NilInput(t *testing.T) {
+	opts := buildXhttpClashOpts(nil)
+	if opts != nil {
+		t.Fatalf("expected nil for nil input, got %#v", opts)
+	}
+}
+
+func TestBuildXhttpClashOpts_EmptyInput(t *testing.T) {
+	opts := buildXhttpClashOpts(map[string]any{})
+	if opts != nil {
+		t.Fatalf("expected nil for empty input, got %#v", opts)
+	}
+}
+
+func TestBuildXhttpClashOpts_HostFallbackFromHeaders(t *testing.T) {
+	// Sub-test 1: host from headers.Host
+	t.Run("HostFromHeaders", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path":    "/",
+			"headers": map[string]any{"Host": "via-header.example.com"},
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		if opts["host"] != "via-header.example.com" {
+			t.Errorf("host = %v, want via-header.example.com", opts["host"])
+		}
+	})
+
+	// Sub-test 2: headers only contains Host — no headers key in output
+	t.Run("HeadersOnlyHost", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path":    "/",
+			"headers": map[string]any{"Host": "only-host.example.com"},
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		if _, has := opts["headers"]; has {
+			t.Error("headers key should not appear when only Host is present (Host is extracted to top-level)")
+		}
+	})
+
+	// Sub-test 3: case-insensitive Host drop
+	t.Run("CaseInsensitiveHostDrop", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path": "/",
+			"host": "explicit.example.com",
+			"headers": map[string]any{
+				"host":     "lowercase-host.example.com",
+				"X-Custom": "value",
+			},
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		if opts["host"] != "explicit.example.com" {
+			t.Errorf("host = %v, want explicit.example.com (explicit host wins)", opts["host"])
+		}
+		headers, ok := opts["headers"].(map[string]any)
+		if !ok {
+			t.Fatal("headers should be present (X-Custom remains)")
+		}
+		if _, has := headers["host"]; has {
+			t.Error("lowercase 'host' should be dropped from headers")
+		}
+		if headers["X-Custom"] != "value" {
+			t.Errorf("X-Custom = %v, want value", headers["X-Custom"])
+		}
+	})
+}
+
+func TestBuildXhttpClashOpts_NoGRPCHeaderFalsey(t *testing.T) {
+	// Sub-test 1: noGRPCHeader: false
+	t.Run("ExplicitFalse", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path":         "/",
+			"noGRPCHeader": false,
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts (path is present)")
+		}
+		if _, has := opts["no-grpc-header"]; has {
+			t.Error("no-grpc-header should not appear when noGRPCHeader is false")
+		}
+	})
+
+	// Sub-test 2: noGRPCHeader absent
+	t.Run("Absent", func(t *testing.T) {
+		xhttp := map[string]any{
+			"path": "/",
+		}
+		opts := buildXhttpClashOpts(xhttp)
+		if opts == nil {
+			t.Fatal("expected non-nil opts")
+		}
+		if _, has := opts["no-grpc-header"]; has {
+			t.Error("no-grpc-header should not appear when absent")
+		}
+	})
+}