fix(xray): reject configs xray-core refuses, and check the fixtures against it

The frontend's golden fixtures are the panel's model of an xray config, but nothing ever asked xray-core whether it would accept them: the snapshots only prove the Zod schemas agree with themselves. Building every fixture through the same config builders the panel hands its config to — conf.InboundDetourConfig for the full-config and AddInbound paths, conf.RouterConfig for ApplyRoutingConfig, conf.DNSConfig for the dns section — found seven the core refuses, three of them reachable from the panel's own UI. A refusal is not scoped to one inbound: the config fails to load and every inbound stays down. Hysteria: xray-core builds version 2 only, in both the protocol settings and the transport settings, but the inbound settings schema accepted any version from 1 up and its comment claimed upstream still supported v1. Both fixtures carried version 1. The schema now pins 2, GenXrayInboundConfig heals stored rows on the way out the way it already heals shadowsocks ciphers and wireguard peers, and the share link drops the dead hysteria:// scheme — the subscription server already emitted hysteria2:// for the same inbound. XHTTP uplinkDataPlacement: both transport forms offered "query", which the core has never accepted for that field (auto and body always, cookie and header in packet-up mode). Replaced with auto, which was missing, and the default label now names auto rather than body. FinalMask items: switching an item to the rand-driven array kind wrote packet:[] next to the rand. xray-core counts an empty array as a packet and every item kind is exclusive, so noise answers "len(item.Packet) > 0 && item.Rand.To > 0" and header-custom "exactly one item kind must be set". The editor now clears the packet, and GetXrayConfig strips the residue from rows already saved with it. The remaining four were stale fixtures: an xmc mask still on the usernames shape v26.7.28 replaced with profiles, a fragment mask with no length, and header-custom and noise items passing an array to the string packet kind — all shapes the panel's own editors cannot produce. golden_fixtures_xray_test.go keeps this from drifting again: every fixture in every category is built through xray-core on each run, with a self-signed pair standing in for the deployment certificate paths, so the next core bump reports which fixture it broke.
2026-08-09 21:00:58 +00:00 · 2026-07-28 14:43:55 +02:00
parent fea6a20f7c
commit dc6a16019e
25 changed files with 931 additions and 69 deletions
@@ -0,0 +1,160 @@
+package service
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+)
+
+func streamWithNoiseItem(t *testing.T, item map[string]any) map[string]any {
+	t.Helper()
+	return map[string]any{
+		"network": "tcp",
+		"finalmask": map[string]any{
+			"udp": []any{map[string]any{
+				"type": "noise",
+				"settings": map[string]any{
+					"reset": "60",
+					"noise": []any{item},
+				},
+			}},
+		},
+	}
+}
+
+func noiseItem(t *testing.T, stream map[string]any) map[string]any {
+	t.Helper()
+	finalmask, _ := stream["finalmask"].(map[string]any)
+	udp, _ := finalmask["udp"].([]any)
+	mask, _ := udp[0].(map[string]any)
+	settings, _ := mask["settings"].(map[string]any)
+	noise, _ := settings["noise"].([]any)
+	item, _ := noise[0].(map[string]any)
+	return item
+}
+
+// TestDropEmptyRandPacketsClearsEditorResidue is the regression for the mask
+// editor writing packet:[] alongside a rand. xray-core counts the empty array
+// as a packet and refuses the config, which keeps every inbound offline.
+func TestDropEmptyRandPacketsClearsEditorResidue(t *testing.T) {
+	stream := streamWithNoiseItem(t, map[string]any{
+		"type":   "array",
+		"rand":   "1-8192",
+		"packet": []any{},
+		"delay":  "5",
+	})
+
+	if cleared := dropEmptyRandPackets(stream["finalmask"]); cleared != 1 {
+		t.Fatalf("cleared = %d, want 1", cleared)
+	}
+	item := noiseItem(t, stream)
+	if _, present := item["packet"]; present {
+		t.Fatalf("packet survived: %#v", item)
+	}
+	if item["rand"] != "1-8192" || item["delay"] != "5" {
+		t.Fatalf("healing changed the mask: %#v", item)
+	}
+}
+
+func TestDropEmptyRandPacketsLeavesRealPacketsAlone(t *testing.T) {
+	tests := []struct {
+		name string
+		item map[string]any
+	}{
+		{"packet without a rand", map[string]any{"type": "array", "packet": []any{1.0, 2.0}, "rand": 0.0}},
+		{"empty packet without a rand", map[string]any{"type": "array", "packet": []any{}}},
+		{"empty packet with a zero rand", map[string]any{"type": "array", "packet": []any{}, "rand": 0.0}},
+		{"empty packet with a zero range", map[string]any{"type": "array", "packet": []any{}, "rand": "0-0"}},
+		{"string packet", map[string]any{"type": "str", "packet": "ping", "rand": "1-10"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			stream := streamWithNoiseItem(t, tt.item)
+			if cleared := dropEmptyRandPackets(stream["finalmask"]); cleared != 0 {
+				t.Fatalf("cleared = %d, want the item left alone", cleared)
+			}
+			if _, present := noiseItem(t, stream)["packet"]; !present {
+				t.Fatal("packet was dropped")
+			}
+		})
+	}
+}
+
+// TestDropEmptyRandPacketsReachesNestedItems covers header-custom, whose items
+// sit two arrays deep and are subject to the same exclusive-kind rule.
+func TestDropEmptyRandPacketsReachesNestedItems(t *testing.T) {
+	stream := map[string]any{
+		"finalmask": map[string]any{
+			"tcp": []any{map[string]any{
+				"type": "header-custom",
+				"settings": map[string]any{
+					"clients": []any{[]any{map[string]any{"type": "array", "rand": 64.0, "packet": []any{}}}},
+					"servers": []any{[]any{map[string]any{"type": "array", "rand": 32.0, "packet": []any{}}}},
+				},
+			}},
+		},
+	}
+	if cleared := dropEmptyRandPackets(stream["finalmask"]); cleared != 2 {
+		t.Fatalf("cleared = %d, want 2", cleared)
+	}
+}
+
+func TestDropEmptyRandPacketsIgnoresMissingFinalMask(t *testing.T) {
+	stream := map[string]any{"network": "tcp"}
+	if cleared := dropEmptyRandPackets(stream["finalmask"]); cleared != 0 {
+		t.Fatalf("cleared = %d, want 0", cleared)
+	}
+}
+
+// TestHealedConfigsBuildInXray closes the loop on both heals: the rows xray
+// refuses outright must build once the panel has healed them.
+func TestHealedConfigsBuildInXray(t *testing.T) {
+	t.Run("hysteria v1 row", func(t *testing.T) {
+		in := model.Inbound{
+			Protocol:       model.Hysteria,
+			Port:           36715,
+			Listen:         "127.0.0.1",
+			Tag:            "in-hysteria",
+			Settings:       `{"version":1,"clients":[{"auth":"tok","email":"a@x"}]}`,
+			StreamSettings: `{"network":"hysteria","hysteriaSettings":{"version":1,"udpIdleTimeout":60}}`,
+		}
+
+		raw, err := json.Marshal(in.GenXrayInboundConfig())
+		if err != nil {
+			t.Fatalf("marshal generated inbound: %v", err)
+		}
+		var healed map[string]any
+		if err := json.Unmarshal(raw, &healed); err != nil {
+			t.Fatalf("decode generated inbound: %v", err)
+		}
+		assertXrayAccepts(t, "the healed hysteria inbound", buildGoldenInbound(t, healed))
+
+		var unhealed map[string]any
+		if err := json.Unmarshal([]byte(`{
+			"tag":"in-hysteria","listen":"127.0.0.1","port":36715,"protocol":"hysteria",
+			"settings":`+in.Settings+`,"streamSettings":`+in.StreamSettings+`}`), &unhealed); err != nil {
+			t.Fatalf("decode raw inbound: %v", err)
+		}
+		if err := buildGoldenInbound(t, unhealed); err == nil {
+			t.Fatal("the unhealed v1 row is expected to be refused; the heal is what makes it buildable")
+		}
+	})
+
+	t.Run("noise item with an empty packet", func(t *testing.T) {
+		item := map[string]any{"type": "array", "rand": "1-8192", "packet": []any{}, "delay": "5"}
+		stream := streamWithNoiseItem(t, item)
+		inbound := map[string]any{
+			"tag": "in-vless", "listen": "127.0.0.1", "port": 8443, "protocol": "vless",
+			"settings":       map[string]any{"clients": []any{}, "decryption": "none"},
+			"streamSettings": stream,
+		}
+		if err := buildGoldenInbound(t, inbound); err == nil {
+			t.Fatal("xray-core is expected to refuse a packet and a rand on one item")
+		}
+
+		dropEmptyRandPackets(stream["finalmask"])
+		inbound["streamSettings"] = stream
+		assertXrayAccepts(t, "the healed noise mask", buildGoldenInbound(t, inbound))
+	})
+}
@@ -0,0 +1,351 @@
+package service
+
+import (
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/json"
+	"encoding/pem"
+	"math/big"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+
+	"github.com/xtls/xray-core/infra/conf"
+)
+
+// The frontend's golden fixtures are the panel's model of an xray config: the
+// Zod snapshots pin what the forms parse and emit. Parsing proves the panel
+// agrees with itself, not that xray-core would accept the result, so every
+// fixture is also built here through the very config builders the panel hands
+// its config to — conf.InboundDetourConfig for the full-config and AddInbound
+// paths, conf.RouterConfig for ApplyRoutingConfig, conf.DNSConfig for the dns
+// section. A fixture xray-core refuses is a config the panel would let an
+// admin save and then fail to start the core with, taking every inbound down.
+//
+// mtproto is excluded: it is served by the bundled mtg-multi sidecar, not by
+// xray, so xray-core has no config id for it.
+
+func goldenFixtureDir(t *testing.T, category string) string {
+	t.Helper()
+	dir, err := filepath.Abs(filepath.Join("..", "..", "..", "frontend", "src", "test", "golden", "fixtures", category))
+	if err != nil {
+		t.Fatalf("resolve fixture dir: %v", err)
+	}
+	return dir
+}
+
+// goldenFixtures returns every fixture in a category as name -> decoded object.
+func goldenFixtures(t *testing.T, category string) map[string]map[string]any {
+	t.Helper()
+	dir := goldenFixtureDir(t, category)
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatalf("read %s: %v", dir, err)
+	}
+	out := make(map[string]map[string]any)
+	names := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if filepath.Ext(entry.Name()) != ".json" {
+			continue
+		}
+		names = append(names, entry.Name())
+	}
+	sort.Strings(names)
+	if len(names) == 0 {
+		t.Fatalf("no fixtures under %s", dir)
+	}
+	for _, name := range names {
+		raw, err := os.ReadFile(filepath.Join(dir, name))
+		if err != nil {
+			t.Fatalf("read %s: %v", name, err)
+		}
+		var obj map[string]any
+		if err := json.Unmarshal(raw, &obj); err != nil {
+			t.Fatalf("unmarshal %s: %v", name, err)
+		}
+		out[strings.TrimSuffix(name, ".json")] = obj
+	}
+	return out
+}
+
+// writeTestCertificate writes a self-signed certificate and key, returning both
+// paths. The TLS fixtures point certificateFile/keyFile at deployment paths
+// that do not exist here, and xray-core reads them while building.
+func writeTestCertificate(t *testing.T) (certPath, keyPath string) {
+	t.Helper()
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatalf("generate key: %v", err)
+	}
+	template := x509.Certificate{
+		SerialNumber: big.NewInt(1),
+		Subject:      pkix.Name{CommonName: "golden-fixture.test"},
+		NotBefore:    time.Now().Add(-time.Hour),
+		NotAfter:     time.Now().Add(24 * time.Hour),
+		DNSNames:     []string{"golden-fixture.test"},
+	}
+	der, err := x509.CreateCertificate(rand.Reader, &template, &template, &key.PublicKey, key)
+	if err != nil {
+		t.Fatalf("create certificate: %v", err)
+	}
+	keyDER, err := x509.MarshalECPrivateKey(key)
+	if err != nil {
+		t.Fatalf("marshal key: %v", err)
+	}
+
+	dir := t.TempDir()
+	certPath = filepath.Join(dir, "fixture.crt")
+	keyPath = filepath.Join(dir, "fixture.key")
+	certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
+	keyPEM := pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER})
+	if err := os.WriteFile(certPath, certPEM, 0o600); err != nil {
+		t.Fatalf("write certificate: %v", err)
+	}
+	if err := os.WriteFile(keyPath, keyPEM, 0o600); err != nil {
+		t.Fatalf("write key: %v", err)
+	}
+	return certPath, keyPath
+}
+
+// repointCertificateFiles rewrites every certificateFile/keyFile reference to
+// the generated pair, so a fixture is judged on its shape rather than on paths
+// that only exist on a deployed server.
+func repointCertificateFiles(node any, certPath, keyPath string) {
+	switch value := node.(type) {
+	case map[string]any:
+		for key, child := range value {
+			switch key {
+			case "certificateFile":
+				if _, ok := child.(string); ok {
+					value[key] = certPath
+					continue
+				}
+			case "keyFile":
+				if _, ok := child.(string); ok {
+					value[key] = keyPath
+					continue
+				}
+			}
+			repointCertificateFiles(child, certPath, keyPath)
+		}
+	case []any:
+		for _, child := range value {
+			repointCertificateFiles(child, certPath, keyPath)
+		}
+	}
+}
+
+// assertXrayAccepts fails unless xray-core built the fixture. Fixtures naming
+// geoip:/geosite: need the dat files the panel ships next to the xray binary;
+// where they are absent the loader fails on the missing file rather than on the
+// fixture, so those are skipped instead of reported as broken.
+func assertXrayAccepts(t *testing.T, subject string, err error) {
+	t.Helper()
+	if err == nil {
+		return
+	}
+	if isMissingGeoAssetErr(err) {
+		t.Skipf("geo data files not available, cannot judge %s: %v", subject, err)
+	}
+	t.Fatalf("xray-core refuses %s: %v", subject, err)
+}
+
+func buildGoldenInbound(t *testing.T, inbound map[string]any) error {
+	t.Helper()
+	certPath, keyPath := writeTestCertificate(t)
+	repointCertificateFiles(inbound, certPath, keyPath)
+
+	raw, err := json.Marshal(inbound)
+	if err != nil {
+		t.Fatalf("marshal inbound: %v", err)
+	}
+	detour := new(conf.InboundDetourConfig)
+	if err := json.Unmarshal(raw, detour); err != nil {
+		return err
+	}
+	_, err = detour.Build()
+	return err
+}
+
+// TestGoldenInboundFixturesBuildInXray wraps each protocol fixture in a minimal
+// inbound and builds it.
+func TestGoldenInboundFixturesBuildInXray(t *testing.T) {
+	for name, fixture := range goldenFixtures(t, "inbound") {
+		if protocol, _ := fixture["protocol"].(string); protocol == string(model.MTProto) {
+			continue
+		}
+		t.Run(name, func(t *testing.T) {
+			inbound := map[string]any{
+				"tag":      "golden-in",
+				"listen":   "127.0.0.1",
+				"port":     8443,
+				"protocol": fixture["protocol"],
+				"settings": fixture["settings"],
+			}
+			assertXrayAccepts(t, "this fixture", buildGoldenInbound(t, inbound))
+		})
+	}
+}
+
+// TestGoldenInboundFullFixturesBuildInXray runs the complete panel Inbound
+// model through GenXrayInboundConfig, the conversion both the full-config and
+// the live AddInbound paths use, and builds the result.
+func TestGoldenInboundFullFixturesBuildInXray(t *testing.T) {
+	for name, fixture := range goldenFixtures(t, "inbound-full") {
+		protocol, _ := fixture["protocol"].(string)
+		if protocol == string(model.MTProto) {
+			continue
+		}
+		t.Run(name, func(t *testing.T) {
+			section := func(key string) string {
+				value, ok := fixture[key]
+				if !ok || value == nil {
+					return ""
+				}
+				raw, err := json.Marshal(value)
+				if err != nil {
+					t.Fatalf("marshal %s: %v", key, err)
+				}
+				return string(raw)
+			}
+			port := 0
+			if p, ok := fixture["port"].(float64); ok {
+				port = int(p)
+			}
+			listen, _ := fixture["listen"].(string)
+			tag, _ := fixture["tag"].(string)
+
+			ib := &model.Inbound{
+				Protocol:       model.Protocol(protocol),
+				Port:           port,
+				Listen:         listen,
+				Tag:            tag,
+				Settings:       section("settings"),
+				StreamSettings: section("streamSettings"),
+				Sniffing:       section("sniffing"),
+			}
+			raw, err := json.Marshal(ib.GenXrayInboundConfig())
+			if err != nil {
+				t.Fatalf("marshal generated inbound: %v", err)
+			}
+			var generated map[string]any
+			if err := json.Unmarshal(raw, &generated); err != nil {
+				t.Fatalf("decode generated inbound: %v", err)
+			}
+			assertXrayAccepts(t, "the generated inbound", buildGoldenInbound(t, generated))
+		})
+	}
+}
+
+// TestGoldenStreamFixturesBuildInXray attaches the transport fragments — whole
+// stream sections, the security block, sockopt and finalmask — to an inbound.
+func TestGoldenStreamFixturesBuildInXray(t *testing.T) {
+	for _, category := range []string{"stream", "security", "sockopt", "finalmask"} {
+		for name, fixture := range goldenFixtures(t, category) {
+			t.Run(category+"/"+name, func(t *testing.T) {
+				stream := map[string]any{"network": "tcp"}
+				switch category {
+				case "stream":
+					stream = fixture
+				case "security":
+					for key, value := range fixture {
+						stream[key] = value
+					}
+				case "sockopt":
+					stream["sockopt"] = fixture
+				case "finalmask":
+					stream["finalmask"] = fixture
+				}
+				inbound := map[string]any{
+					"tag": "golden-in", "listen": "127.0.0.1", "port": 8443, "protocol": "vless",
+					"settings": map[string]any{
+						"clients":    []any{map[string]any{"id": "b831381d-6324-4d53-ad4f-8cda48b30811", "email": "golden"}},
+						"decryption": "none",
+					},
+					"streamSettings": stream,
+				}
+				assertXrayAccepts(t, "this fixture", buildGoldenInbound(t, inbound))
+			})
+		}
+	}
+}
+
+func buildGoldenRouting(routing map[string]any) error {
+	raw, err := json.Marshal(routing)
+	if err != nil {
+		return err
+	}
+	router := new(conf.RouterConfig)
+	if err := json.Unmarshal(raw, router); err != nil {
+		return err
+	}
+	_, err = router.Build()
+	return err
+}
+
+// TestGoldenRoutingFixturesBuildInXray builds the rule and balancer fixtures
+// through the router config ApplyRoutingConfig hands to the running core.
+func TestGoldenRoutingFixturesBuildInXray(t *testing.T) {
+	for name, rule := range goldenFixtures(t, "rule") {
+		t.Run("rule/"+name, func(t *testing.T) {
+			assertXrayAccepts(t, "this rule", buildGoldenRouting(map[string]any{
+				"domainStrategy": "AsIs",
+				"rules":          []any{rule},
+				"balancers":      []any{map[string]any{"tag": "balancer-load", "selector": []any{"proxy-"}}},
+			}))
+		})
+	}
+
+	for name, balancer := range goldenFixtures(t, "balancer") {
+		t.Run("balancer/"+name, func(t *testing.T) {
+			assertXrayAccepts(t, "this balancer", buildGoldenRouting(map[string]any{
+				"domainStrategy": "AsIs",
+				"balancers":      []any{balancer},
+				"rules": []any{map[string]any{
+					"type": "field", "port": "443", "balancerTag": balancer["tag"],
+				}},
+			}))
+		})
+	}
+}
+
+// TestGoldenDNSFixturesBuildInXray builds the dns section, and each dns-server
+// fixture inside one.
+func TestGoldenDNSFixturesBuildInXray(t *testing.T) {
+	build := func(dns map[string]any) error {
+		raw, err := json.Marshal(dns)
+		if err != nil {
+			return err
+		}
+		dnsConf := new(conf.DNSConfig)
+		if err := json.Unmarshal(raw, dnsConf); err != nil {
+			return err
+		}
+		_, err = dnsConf.Build()
+		return err
+	}
+
+	for name, fixture := range goldenFixtures(t, "dns") {
+		t.Run("dns/"+name, func(t *testing.T) {
+			assertXrayAccepts(t, "this dns section", build(fixture))
+		})
+	}
+	for name, server := range goldenFixtures(t, "dns-server") {
+		t.Run("dns-server/"+name, func(t *testing.T) {
+			assertXrayAccepts(t, "this dns server", build(map[string]any{"servers": []any{server}}))
+		})
+	}
+}
+
+func isMissingGeoAssetErr(err error) bool {
+	msg := err.Error()
+	return strings.Contains(msg, "geoip.dat") || strings.Contains(msg, "geosite.dat")
+}
@@ -713,6 +713,52 @@ func stripIncompleteXmcMasks(stream map[string]any) int {
 	return dropped
 }

+// dropEmptyRandPackets removes the leftover empty "packet" from finalmask
+// items that also carry a rand, and reports how many it cleared.
+//
+// xray-core treats even an empty array as a packet, and every item kind is
+// exclusive: noise refuses "len(item.Packet) > 0 && item.Rand.To > 0" and
+// header-custom refuses "exactly one item kind must be set". Either error
+// fails the whole config build, so one such item keeps every inbound offline.
+// The panel's mask editor wrote that pair whenever an item was switched to the
+// rand-driven array kind, so stored rows carry it; clearing an empty packet
+// changes nothing about the mask the admin configured.
+func dropEmptyRandPackets(node any) int {
+	switch value := node.(type) {
+	case map[string]any:
+		cleared := 0
+		if packet, ok := value["packet"].([]any); ok && len(packet) == 0 && randIsSet(value["rand"]) {
+			delete(value, "packet")
+			cleared++
+		}
+		for _, child := range value {
+			cleared += dropEmptyRandPackets(child)
+		}
+		return cleared
+	case []any:
+		cleared := 0
+		for _, child := range value {
+			cleared += dropEmptyRandPackets(child)
+		}
+		return cleared
+	default:
+		return 0
+	}
+}
+
+// randIsSet reports whether a finalmask item's rand selects a random packet.
+// It is a number on header-custom items and a dash-range string on noise ones.
+func randIsSet(value any) bool {
+	switch rand := value.(type) {
+	case float64:
+		return rand > 0
+	case string:
+		return rand != "" && rand != "0" && rand != "0-0"
+	default:
+		return false
+	}
+}
+
 // validateFinalMaskXmcProfiles rejects an xmc finalmask without complete
 // profiles at save time, so the admin gets a targeted error instead of a core
 // that refuses to start (or, after GetXrayConfig heals it, an inbound quietly
@@ -281,6 +281,8 @@ func (s *XrayService) GetXrayConfig() (*xray.Config, error) {
 				delete(stream, "finalmask")
 			}

+			dropEmptyRandPackets(stream["finalmask"])
+
 			if dropped := stripIncompleteXmcMasks(stream); dropped > 0 {
 				logger.Warningf("Inbound %q: dropping %d XMC finalmask mask(s) without complete Minecraft profiles — reconfigure them to restore the obfuscation (see XTLS/Xray-core#6487)", inbound.Tag, dropped)
 			}