fix(finalmask): hop client UDP through the udphop mask

xray-core 26.9.9 dropped finalmask.quicParams.udpHop for the client-only
"udphop" UDP mask {mode, interval, remoteIPs, remotePorts}. The panel kept
writing the old key, so hysteria/xhttp outbounds and JSON-subscription
clients silently stopped hopping ports.

An inbound keeps quicParams.udpHop: it is panel metadata advertised as the
link's mport, and a udphop mask on a listener fails with "udphop: client
only". The conversion (maskcompat.UpgradeLegacyUDPHop, intervalRemote mode)
runs only where a client config is produced:

- UDPHopClientMaskFix seeder over hosts, sub-JSON finalmask, cached
  outbound-subscription outbounds and template outbounds (never inbounds);
- GetXrayConfig heals template outbounds at build time;
- the JSON subscription upgrades each generated client stream;
- the Go and frontend link importers upgrade a legacy fm= param.

The finalmask editor gains a side prop: the client side lifts the dead key
on mount and offers a udphop mask editor (also for xhttp's HTTP/3 dial);
the inbound side keeps the UDP Hop switch, labelled as advertised.

internal/util/link/outbound.go

@@ -769,6 +769,7 @@ func applyFinalMask(stream map[string]any, p url.Values) {
 		if json.Unmarshal([]byte(fm), &parsed) == nil {
 			sanitizeFinalMaskQuicParams(parsed)
 			maskcompat.UpgradeLegacyXdns(parsed)
+			maskcompat.UpgradeLegacyUDPHop(parsed)
 			stream["finalmask"] = parsed
 		}
 	}

internal/util/link/outbound_test.go

@@ -304,9 +304,9 @@ func TestParseHysteria2_Mport(t *testing.T) {
 			wantHop:   true,
 		},
 		{
-			name:      "legacy fm quicParams.udpHop no longer suppresses mport",
+			name:      "legacy fm quicParams.udpHop is upgraded and wins over mport like the mask",
 			query:     "mport=1-2&fm=" + url.QueryEscape(`{"quicParams":{"udpHop":{"ports":"30000-40000","interval":"7-9"}}}`),
-			wantPorts: "1-2",
+			wantPorts: "30000-40000",
 			wantHop:   true,
 		},
 	}
@@ -577,3 +577,22 @@ func TestParseShadowsocksObfsLocalPlugin(t *testing.T) {
 		})
 	}
 }
+
+// A panel older than the 26.9.9 core shares its hop range as quicParams.udpHop inside fm=,
+// which the core ignores; imported verbatim, the outbound would never hop.
+func TestParseLink_UpgradesLegacyUDPHopFinalMask(t *testing.T) {
+	fm := url.QueryEscape(`{"quicParams":{"udpHop":{"ports":"20000-30000","interval":"5-10"}}}`)
+	res, err := ParseLink("hysteria2://auth@hy.example.com:443?sni=hy.example.com&fm=" + fm + "#hy")
+	if err != nil {
+		t.Fatalf("parse hysteria2 with fm: %v", err)
+	}
+	stream, _ := res.Outbound["streamSettings"].(map[string]any)
+	got, err := json.Marshal(stream["finalmask"])
+	if err != nil {
+		t.Fatalf("marshal finalmask: %v", err)
+	}
+	want := `{"udp":[{"settings":{"interval":"5-10","mode":"intervalRemote","remotePorts":"20000-30000"},"type":"udphop"}]}`
+	if string(got) != want {
+		t.Fatalf("imported finalmask\n got: %s\nwant: %s", got, want)
+	}
+}

internal/util/maskcompat/udphop.go

@@ -0,0 +1,54 @@
+package maskcompat
+
+import "strings"
+
+// UpgradeLegacyUDPHop moves the quicParams.udpHop range xray-core 26.9.9 stopped reading
+// into the client-only "udphop" UDP mask, whose intervalRemote mode is what the key did.
+func UpgradeLegacyUDPHop(finalmask any) bool {
+	fm, _ := finalmask.(map[string]any)
+	quicParams, _ := fm["quicParams"].(map[string]any)
+	legacy, found := quicParams["udpHop"]
+	if !found {
+		return false
+	}
+	delete(quicParams, "udpHop")
+	if len(quicParams) == 0 {
+		delete(fm, "quicParams")
+	}
+
+	hop, _ := legacy.(map[string]any)
+	ports := hop["ports"]
+	if isEmptyHopValue(ports) || hasUDPHopMask(fm) {
+		return true
+	}
+	settings := map[string]any{"mode": "intervalRemote", "remotePorts": ports}
+	if interval := hop["interval"]; !isEmptyHopValue(interval) {
+		settings["interval"] = interval
+	}
+	masks, _ := fm["udp"].([]any)
+	fm["udp"] = append(masks, map[string]any{"type": "udphop", "settings": settings})
+	return true
+}
+
+func hasUDPHopMask(fm map[string]any) bool {
+	masks, _ := fm["udp"].([]any)
+	for _, entry := range masks {
+		mask, _ := entry.(map[string]any)
+		if maskType, _ := mask["type"].(string); strings.EqualFold(maskType, "udphop") {
+			return true
+		}
+	}
+	return false
+}
+
+func isEmptyHopValue(value any) bool {
+	switch v := value.(type) {
+	case nil:
+		return true
+	case string:
+		return strings.TrimSpace(v) == ""
+	case float64:
+		return v == 0
+	}
+	return false
+}

internal/util/maskcompat/udphop_test.go

@@ -0,0 +1,106 @@
+package maskcompat
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/xtls/xray-core/infra/conf"
+	"github.com/xtls/xray-core/transport/internet/finalmask/udphop"
+)
+
+// coreUDPHop builds a finalmask's UDP masks through conf.Mask, the loader the core
+// calls at startup, and returns the udphop config the client would hop with, if any.
+func coreUDPHop(t *testing.T, finalmask map[string]any) *udphop.Config {
+	t.Helper()
+	raw, err := json.Marshal(finalmask)
+	if err != nil {
+		t.Fatalf("marshal finalmask: %v", err)
+	}
+	var fm conf.FinalMask
+	if err := json.Unmarshal(raw, &fm); err != nil {
+		t.Fatalf("decode finalmask: %v", err)
+	}
+	for _, mask := range fm.Udp {
+		built, err := mask.Build(false)
+		if err != nil {
+			t.Fatalf("the core refuses UDP mask %q: %v", mask.Type, err)
+		}
+		if hop, ok := built.(*udphop.Config); ok {
+			return hop
+		}
+	}
+	return nil
+}
+
+func decodeFinalmask(t *testing.T, s string) map[string]any {
+	t.Helper()
+	var fm map[string]any
+	if err := json.Unmarshal([]byte(s), &fm); err != nil {
+		t.Fatalf("decode finalmask: %v", err)
+	}
+	return fm
+}
+
+func TestUpgradeLegacyUDPHop(t *testing.T) {
+	fm := decodeFinalmask(t, `{"udp":[{"type":"salamander","settings":{"password":"p"}}],
+		"quicParams":{"congestion":"bbr","udpHop":{"ports":"20000-20003","interval":"5-10"}}}`)
+	if hop := coreUDPHop(t, fm); hop != nil {
+		t.Fatal("the core hops on quicParams.udpHop again; the upgrade is no longer needed")
+	}
+
+	if !UpgradeLegacyUDPHop(fm) {
+		t.Fatal("UpgradeLegacyUDPHop reported no change for a legacy hop")
+	}
+	got, _ := json.Marshal(fm)
+	const want = `{"quicParams":{"congestion":"bbr"},"udp":[{"settings":{"password":"p"},"type":"salamander"},{"settings":{"interval":"5-10","mode":"intervalRemote","remotePorts":"20000-20003"},"type":"udphop"}]}`
+	if string(got) != want {
+		t.Fatalf("upgraded finalmask\n got: %s\nwant: %s", got, want)
+	}
+	hop := coreUDPHop(t, fm)
+	if hop == nil || !hop.Remote || hop.Local || hop.IntervalMin != 5 || hop.IntervalMax != 10 ||
+		len(hop.RemotePorts) != 4 || hop.RemotePorts[0] != 20000 || hop.RemotePorts[3] != 20003 {
+		t.Fatalf("the core hops with %+v, want remote ports 20000-20003 every 5-10s", hop)
+	}
+}
+
+func TestUpgradeLegacyUDPHopEdgeCases(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "an explicit udphop mask wins over the dead key",
+			input: `{"udp":[{"type":"udphop","settings":{"mode":"perConnRemote","remotePorts":"443"}}],"quicParams":{"udpHop":{"ports":"20000-30000"}}}`,
+			want:  `{"udp":[{"settings":{"mode":"perConnRemote","remotePorts":"443"},"type":"udphop"}]}`,
+		},
+		{
+			name:  "a hop without ports only loses the dead key",
+			input: `{"quicParams":{"udpHop":{"interval":"5-10"}}}`,
+			want:  `{}`,
+		},
+		{
+			name:  "no interval keeps the core's 30s default",
+			input: `{"quicParams":{"udpHop":{"ports":"443,8443"}}}`,
+			want:  `{"udp":[{"settings":{"mode":"intervalRemote","remotePorts":"443,8443"},"type":"udphop"}]}`,
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			fm := decodeFinalmask(t, tc.input)
+			if !UpgradeLegacyUDPHop(fm) {
+				t.Fatal("UpgradeLegacyUDPHop reported no change")
+			}
+			got, _ := json.Marshal(fm)
+			if string(got) != tc.want {
+				t.Fatalf("upgraded finalmask\n got: %s\nwant: %s", got, tc.want)
+			}
+			coreUDPHop(t, fm)
+		})
+	}
+
+	current := decodeFinalmask(t, `{"udp":[{"type":"udphop","settings":{"mode":"intervalRemote","remotePorts":"443"}}],"quicParams":{"congestion":"bbr"}}`)
+	if UpgradeLegacyUDPHop(current) {
+		t.Fatal("UpgradeLegacyUDPHop rewrote a finalmask without the legacy key")
+	}
+}