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/database/db.go

@@ -1282,7 +1282,7 @@ func runSeeders(isUsersEmpty bool) error {
 	}
 
 	if empty && isUsersEmpty {
-		seeders := []string{"UserPasswordHash", "ClientsTable", "InboundClientsArrayFix", "InboundClientTgIdFix2", "InboundClientSubIdFix", "FreedomFinalRulesReverseFix", "FreedomFinalRulesPrivateEgressBlock", "UppercaseFreedomFinalRulesFix", "InboundRealityFinalmaskTcpStrip", "ApiTokensHash", "LegacyProxySettingsCleanup", "OutboundRemovedKeysFix", "FreedomDomainStrategyFix", "DNSOutboundLegacyKeysFix", "DNSOutboundQTypeZeroFix", "WireguardDomainStrategyFix", "XdnsFinalmaskNamesAddrsFix", "WireguardPeersToClients", "MtprotoSecretsToClients", "NodeInboundsAdopted", "ResetIpLimitNoFail2ban"}
+		seeders := []string{"UserPasswordHash", "ClientsTable", "InboundClientsArrayFix", "InboundClientTgIdFix2", "InboundClientSubIdFix", "FreedomFinalRulesReverseFix", "FreedomFinalRulesPrivateEgressBlock", "UppercaseFreedomFinalRulesFix", "InboundRealityFinalmaskTcpStrip", "ApiTokensHash", "LegacyProxySettingsCleanup", "OutboundRemovedKeysFix", "FreedomDomainStrategyFix", "DNSOutboundLegacyKeysFix", "DNSOutboundQTypeZeroFix", "WireguardDomainStrategyFix", "XdnsFinalmaskNamesAddrsFix", "UDPHopClientMaskFix", "WireguardPeersToClients", "MtprotoSecretsToClients", "NodeInboundsAdopted", "ResetIpLimitNoFail2ban"}
 		for _, name := range seeders {
 			if err := db.Create(&model.HistoryOfSeeders{SeederName: name}).Error; err != nil {
 				return err
@@ -1429,6 +1429,12 @@ func runSeeders(isUsersEmpty bool) error {
 		}
 	}
 
+	if !slices.Contains(seedersHistory, "UDPHopClientMaskFix") {
+		if err := migrateUDPHopClientMasks(); err != nil {
+			return err
+		}
+	}
+
 	if !slices.Contains(seedersHistory, "NodeInboundsAdopted") {
 		if err := seedNodeInboundsAdopted(); err != nil {
 			return err
@@ -1937,7 +1943,7 @@ func migrateXdnsFinalmaskShape() error {
 			return err
 		}
 		for _, inbound := range inbounds {
-			if updated, changed := upgradeLegacyXdnsJSON(inbound.StreamSettings, streamFinalmask, false); changed {
+			if updated, changed := upgradeFinalmasksJSON(inbound.StreamSettings, streamFinalmask, false, maskcompat.UpgradeLegacyXdns); changed {
 				if err := tx.Model(&model.Inbound{}).Where("id = ?", inbound.Id).
 					Update("stream_settings", updated).Error; err != nil {
 					return err
@@ -1949,7 +1955,7 @@ func migrateXdnsFinalmaskShape() error {
 			return err
 		}
 		for _, host := range hosts {
-			if updated, changed := upgradeLegacyXdnsJSON(host.FinalMask, wholeFinalmask, false); changed {
+			if updated, changed := upgradeFinalmasksJSON(host.FinalMask, wholeFinalmask, false, maskcompat.UpgradeLegacyXdns); changed {
 				if err := tx.Model(&model.Host{}).Where("id = ?", host.Id).
 					Update("final_mask", updated).Error; err != nil {
 					return err
@@ -1961,7 +1967,7 @@ func migrateXdnsFinalmaskShape() error {
 			return err
 		}
 		for _, sub := range subs {
-			if updated, changed := upgradeLegacyXdnsJSON(sub.LastFetchedOutbounds, outboundListFinalmasks, false); changed {
+			if updated, changed := upgradeFinalmasksJSON(sub.LastFetchedOutbounds, outboundListFinalmasks, false, maskcompat.UpgradeLegacyXdns); changed {
 				if err := tx.Model(&model.OutboundSubscription{}).Where("id = ?", sub.Id).
 					Update("last_fetched_outbounds", updated).Error; err != nil {
 					return err
@@ -1984,7 +1990,7 @@ func migrateXdnsFinalmaskShape() error {
 			if err != nil {
 				return err
 			}
-			if updated, changed := upgradeLegacyXdnsJSON(setting.Value, stored.locate, stored.indent); changed {
+			if updated, changed := upgradeFinalmasksJSON(setting.Value, stored.locate, stored.indent, maskcompat.UpgradeLegacyXdns); changed {
 				if err := tx.Model(&model.Setting{}).Where("key = ?", stored.key).
 					Update("value", updated).Error; err != nil {
 					return err
@@ -1995,9 +2001,64 @@ func migrateXdnsFinalmaskShape() error {
 	})
 }
 
-// upgradeLegacyXdnsJSON rewrites the finalmasks locate finds in one stored JSON document,
-// leaving the document byte-for-byte alone when nothing in it is legacy.
-func upgradeLegacyXdnsJSON(raw string, locate func(any) []any, indent bool) (string, bool) {
+// migrateUDPHopClientMasks moves the quicParams.udpHop xray-core 26.9.9 ignores into a
+// udphop mask in every client-side finalmask; inbounds keep it, udphop refuses to run there.
+func migrateUDPHopClientMasks() error {
+	return db.Transaction(func(tx *gorm.DB) error {
+		var hosts []model.Host
+		if err := tx.Select("id", "final_mask").Find(&hosts).Error; err != nil {
+			return err
+		}
+		for _, host := range hosts {
+			if updated, changed := upgradeFinalmasksJSON(host.FinalMask, wholeFinalmask, false, maskcompat.UpgradeLegacyUDPHop); changed {
+				if err := tx.Model(&model.Host{}).Where("id = ?", host.Id).
+					Update("final_mask", updated).Error; err != nil {
+					return err
+				}
+			}
+		}
+		var subs []model.OutboundSubscription
+		if err := tx.Select("id", "last_fetched_outbounds").Find(&subs).Error; err != nil {
+			return err
+		}
+		for _, sub := range subs {
+			if updated, changed := upgradeFinalmasksJSON(sub.LastFetchedOutbounds, outboundListFinalmasks, false, maskcompat.UpgradeLegacyUDPHop); changed {
+				if err := tx.Model(&model.OutboundSubscription{}).Where("id = ?", sub.Id).
+					Update("last_fetched_outbounds", updated).Error; err != nil {
+					return err
+				}
+			}
+		}
+		for _, stored := range []struct {
+			key    string
+			locate func(any) []any
+			indent bool
+		}{
+			{"xrayTemplateConfig", templateOutboundFinalmasks, true},
+			{"subJsonFinalMask", wholeFinalmask, false},
+		} {
+			var setting model.Setting
+			err := tx.Where("key = ?", stored.key).First(&setting).Error
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				continue
+			}
+			if err != nil {
+				return err
+			}
+			if updated, changed := upgradeFinalmasksJSON(setting.Value, stored.locate, stored.indent, maskcompat.UpgradeLegacyUDPHop); changed {
+				if err := tx.Model(&model.Setting{}).Where("key = ?", stored.key).
+					Update("value", updated).Error; err != nil {
+					return err
+				}
+			}
+		}
+		return tx.Create(&model.HistoryOfSeeders{SeederName: "UDPHopClientMaskFix"}).Error
+	})
+}
+
+// upgradeFinalmasksJSON runs upgrade on the finalmasks locate finds in one stored JSON
+// document, leaving the document byte-for-byte alone when nothing in it changed.
+func upgradeFinalmasksJSON(raw string, locate func(any) []any, indent bool, upgrade func(any) bool) (string, bool) {
 	if strings.TrimSpace(raw) == "" {
 		return raw, false
 	}
@@ -2007,7 +2068,7 @@ func upgradeLegacyXdnsJSON(raw string, locate func(any) []any, indent bool) (str
 	}
 	changed := false
 	for _, mask := range locate(doc) {
-		if maskcompat.UpgradeLegacyXdns(mask) {
+		if upgrade(mask) {
 			changed = true
 		}
 	}
@@ -2044,6 +2105,11 @@ func outboundListFinalmasks(doc any) []any {
 	return finalmasks
 }
 
+func templateOutboundFinalmasks(doc any) []any {
+	cfg, _ := doc.(map[string]any)
+	return outboundListFinalmasks(cfg["outbounds"])
+}
+
 func templateFinalmasks(doc any) []any {
 	cfg, _ := doc.(map[string]any)
 	return append(outboundListFinalmasks(cfg["inbounds"]), outboundListFinalmasks(cfg["outbounds"])...)

internal/database/udphop_client_mask_migration_test.go

@@ -0,0 +1,117 @@
+package database
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+)
+
+const legacyHopFinalmask = `{"quicParams":{"udpHop":{"ports":"20000-30000","interval":"5-10"}}}`
+
+const upgradedHopFinalmask = `{"udp":[{"settings":{"interval":"5-10","mode":"intervalRemote","remotePorts":"20000-30000"},"type":"udphop"}]}`
+
+func assertHopUpgraded(t *testing.T, where string, finalmask any) {
+	t.Helper()
+	got, err := json.Marshal(finalmask)
+	if err != nil {
+		t.Fatalf("%s: marshal finalmask: %v", where, err)
+	}
+	if string(got) != upgradedHopFinalmask {
+		t.Fatalf("%s: finalmask\n got: %s\nwant: %s", where, got, upgradedHopFinalmask)
+	}
+}
+
+// xray-core 26.9.9 ignores quicParams.udpHop, so every client-side finalmask the panel
+// stored before then hops nowhere; inbounds keep it, since udphop refuses to run there.
+func TestUDPHopSeederMovesClientHopsToTheMask(t *testing.T) {
+	initMigrateDB(t)
+	inboundStream := `{"network":"hysteria","security":"tls","finalmask":` + legacyHopFinalmask + `}`
+	ib := seedInboundWithStream(t, "hy-in", 8443, inboundStream)
+	host := &model.Host{InboundId: ib.Id, Remark: "h", Address: "cdn.example.com", Port: 8443, FinalMask: legacyHopFinalmask}
+	if err := GetDB().Create(host).Error; err != nil {
+		t.Fatalf("create host: %v", err)
+	}
+	seedTemplate(t, `{"inbounds":[{"tag":"tpl-in","streamSettings":{"finalmask":`+legacyHopFinalmask+`}}],
+		"outbounds":[{"protocol":"hysteria","tag":"hy-out","settings":{},"streamSettings":{"network":"hysteria","finalmask":`+legacyHopFinalmask+`}}]}`)
+	if err := GetDB().Create(&model.Setting{Key: "subJsonFinalMask", Value: legacyHopFinalmask}).Error; err != nil {
+		t.Fatalf("seed subJsonFinalMask: %v", err)
+	}
+	sub := &model.OutboundSubscription{
+		Remark: "donor", Url: "https://donor.example.com/sub",
+		LastFetchedOutbounds: `[{"protocol":"hysteria","tag":"sub-1","settings":{},"streamSettings":{"network":"hysteria","finalmask":` + legacyHopFinalmask + `}}]`,
+	}
+	if err := GetDB().Create(sub).Error; err != nil {
+		t.Fatalf("create outbound subscription: %v", err)
+	}
+	if err := GetDB().Where("seeder_name = ?", "UDPHopClientMaskFix").Delete(&model.HistoryOfSeeders{}).Error; err != nil {
+		t.Fatalf("clear seeder history: %v", err)
+	}
+
+	if err := runSeeders(false); err != nil {
+		t.Fatalf("runSeeders: %v", err)
+	}
+
+	var storedHost model.Host
+	if err := GetDB().First(&storedHost, host.Id).Error; err != nil {
+		t.Fatalf("reload host: %v", err)
+	}
+	var hostMask any
+	_ = json.Unmarshal([]byte(storedHost.FinalMask), &hostMask)
+	assertHopUpgraded(t, "host finalMask", hostMask)
+
+	var template struct {
+		Inbounds []struct {
+			StreamSettings struct {
+				Finalmask json.RawMessage `json:"finalmask"`
+			} `json:"streamSettings"`
+		} `json:"inbounds"`
+		Outbounds []struct {
+			StreamSettings struct {
+				Finalmask any `json:"finalmask"`
+			} `json:"streamSettings"`
+		} `json:"outbounds"`
+	}
+	if err := json.Unmarshal([]byte(storedTemplate(t)), &template); err != nil || len(template.Outbounds) != 1 || len(template.Inbounds) != 1 {
+		t.Fatalf("stored template unreadable (%v)", err)
+	}
+	assertHopUpgraded(t, "template outbound", template.Outbounds[0].StreamSettings.Finalmask)
+	var inboundMask any
+	_ = json.Unmarshal(template.Inbounds[0].StreamSettings.Finalmask, &inboundMask)
+	var legacy any
+	_ = json.Unmarshal([]byte(legacyHopFinalmask), &legacy)
+	want, _ := json.Marshal(legacy)
+	if got, _ := json.Marshal(inboundMask); string(got) != string(want) {
+		t.Fatalf("template inbound finalmask = %s, want it untouched", got)
+	}
+
+	var subMask model.Setting
+	if err := GetDB().Where("key = ?", "subJsonFinalMask").First(&subMask).Error; err != nil {
+		t.Fatalf("reload subJsonFinalMask: %v", err)
+	}
+	var subFinalmask any
+	_ = json.Unmarshal([]byte(subMask.Value), &subFinalmask)
+	assertHopUpgraded(t, "subJsonFinalMask", subFinalmask)
+
+	var storedSub model.OutboundSubscription
+	if err := GetDB().First(&storedSub, sub.Id).Error; err != nil {
+		t.Fatalf("reload outbound subscription: %v", err)
+	}
+	var cached []struct {
+		StreamSettings struct {
+			Finalmask any `json:"finalmask"`
+		} `json:"streamSettings"`
+	}
+	if err := json.Unmarshal([]byte(storedSub.LastFetchedOutbounds), &cached); err != nil || len(cached) != 1 {
+		t.Fatalf("cached subscription outbounds unreadable (%v)", err)
+	}
+	assertHopUpgraded(t, "cached subscription outbound", cached[0].StreamSettings.Finalmask)
+
+	var stored model.Inbound
+	if err := GetDB().First(&stored, ib.Id).Error; err != nil {
+		t.Fatalf("reload inbound: %v", err)
+	}
+	if stored.StreamSettings != inboundStream {
+		t.Fatalf("inbound stream = %s, want it untouched", stored.StreamSettings)
+	}
+}

internal/sub/json_service.go

@@ -16,6 +16,7 @@ import (
 	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
 	"github.com/mhsanaei/3x-ui/v3/internal/logger"
 	"github.com/mhsanaei/3x-ui/v3/internal/util/json_util"
+	"github.com/mhsanaei/3x-ui/v3/internal/util/maskcompat"
 	"github.com/mhsanaei/3x-ui/v3/internal/util/random"
 	wgutil "github.com/mhsanaei/3x-ui/v3/internal/util/wireguard"
 )
@@ -640,6 +641,8 @@ func (s *SubJsonService) getConfig(subReq *SubService, inbound *model.Inbound, c
 		if finalmask, ok := newStream["finalmask"].(map[string]any); ok {
 			newStream["finalmask"] = withLegacyFragmentRanges(finalmask)
 		}
+		// An inbound keeps its hop range as quicParams.udpHop; clients hop only with the mask.
+		maskcompat.UpgradeLegacyUDPHop(newStream["finalmask"])
 		streamSettings, _ := json.MarshalIndent(newStream, "", "  ")
 		hostMux := hostMuxOverride(extPrxy)
 
@@ -1001,6 +1004,7 @@ func (s *SubJsonService) genHy(inbound *model.Inbound, newStream map[string]any,
 	if finalmask, ok := hyStream["finalmask"].(map[string]any); ok {
 		newStream["finalmask"] = mergeFinalMask(newStream["finalmask"], finalmask)
 	}
+	maskcompat.UpgradeLegacyUDPHop(newStream["finalmask"])
 
 	newStream["network"] = "hysteria"
 	newStream["security"] = "tls"

internal/sub/masque_test.go

@@ -81,3 +81,36 @@ func TestGetInboundsBySubIdIncludesMasque(t *testing.T) {
 		t.Fatalf("masque inbound not returned for subId: %+v", inbounds)
 	}
 }
+
+// An inbound keeps its hop range in quicParams.udpHop (udphop refuses to run on a server),
+// but the client config must carry the udphop mask: the core ignores the old key since 26.9.9.
+func TestSubJsonServiceTurnsInboundHopIntoClientUDPHopMask(t *testing.T) {
+	inbound := &model.Inbound{
+		Listen: "203.0.113.10", Port: 443, Protocol: model.Hysteria, Remark: "hy",
+		Settings: `{"version":2,"clients":[{"email":"ivy@example.test","auth":"a"}]}`,
+		StreamSettings: `{"network":"hysteria","security":"tls",
+			"hysteriaSettings":{"version":2},
+			"tlsSettings":{"serverName":"hy.example.test","alpn":["h3"]},
+			"finalmask":{"quicParams":{"udpHop":{"ports":"20000-30000","interval":"5-10"}}}}`,
+	}
+	client := model.Client{Email: "ivy@example.test", Auth: "a"}
+
+	configs := NewSubJsonService("", "", "", "", nil).getConfig(&SubService{address: "sub.example.com"}, inbound, client, "sub.example.com")
+	if len(configs) != 1 {
+		t.Fatalf("got %d configs, want one", len(configs))
+	}
+	var config struct {
+		Outbounds []struct {
+			Protocol       string         `json:"protocol"`
+			StreamSettings map[string]any `json:"streamSettings"`
+		} `json:"outbounds"`
+	}
+	if err := json.Unmarshal(configs[0], &config); err != nil {
+		t.Fatalf("decode config: %v", err)
+	}
+	got, _ := json.Marshal(config.Outbounds[0].StreamSettings["finalmask"])
+	const want = `{"udp":[{"settings":{"interval":"5-10","mode":"intervalRemote","remotePorts":"20000-30000"},"type":"udphop"}]}`
+	if string(got) != want {
+		t.Fatalf("client finalmask\n got: %s\nwant: %s", got, want)
+	}
+}

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")
+	}
+}

internal/web/service/inbound_finalmask_xdns_test.go

@@ -113,3 +113,38 @@ func TestGetXrayConfig_UpgradesTemplateOutboundXdnsMask(t *testing.T) {
 	}
 	t.Fatal("outbound dns-tunnel not found in the generated config")
 }
+
+// A hysteria outbound pasted from a pre-26.9.9 template still carries quicParams.udpHop,
+// which the core now ignores; the build heal hands it the udphop mask instead.
+func TestGetXrayConfig_UpgradesTemplateOutboundUDPHop(t *testing.T) {
+	setupConflictDB(t)
+	template := `{"outbounds":[{"protocol":"freedom","tag":"direct"},{"protocol":"hysteria","tag":"hy-out",
+		"settings":{"version":2,"address":"hy.example.com","port":443},
+		"streamSettings":{"network":"hysteria","security":"tls","hysteriaSettings":{"version":2,"auth":"a"},
+			"finalmask":{"quicParams":{"udpHop":{"ports":"20000-30000","interval":"5-10"}}}}}]}`
+	if err := (&SettingService{}).saveSetting("xrayTemplateConfig", template); err != nil {
+		t.Fatalf("seed template: %v", err)
+	}
+
+	cfg, err := (&XrayService{}).GetXrayConfig()
+	if err != nil {
+		t.Fatalf("GetXrayConfig: %v", err)
+	}
+	var outbounds []map[string]any
+	if err := json.Unmarshal(cfg.OutboundConfigs, &outbounds); err != nil {
+		t.Fatalf("decode emitted outbounds: %v", err)
+	}
+	for _, outbound := range outbounds {
+		if outbound["tag"] != "hy-out" {
+			continue
+		}
+		stream, _ := outbound["streamSettings"].(map[string]any)
+		got, _ := json.Marshal(stream["finalmask"])
+		const want = `{"udp":[{"settings":{"interval":"5-10","mode":"intervalRemote","remotePorts":"20000-30000"},"type":"udphop"}]}`
+		if string(got) != want {
+			t.Fatalf("emitted finalmask\n got: %s\nwant: %s", got, want)
+		}
+		return
+	}
+	t.Fatal("outbound hy-out not found in the generated config")
+}

internal/web/service/xray.go

@@ -180,10 +180,10 @@ func (s *XrayService) GetXrayConfig() (*xray.Config, error) {
 	xrayConfig.API = ensureAPIServices(xrayConfig.API)
 	xrayConfig.Policy = ensureStatsPolicy(xrayConfig.Policy)
 	xrayConfig.RouterConfig = stripDisabledRules(xrayConfig.RouterConfig)
-	// A pasted or restored template can still carry pre-#6258 XHTTP session keys or a
-	// pre-26.10.10 xdns mask the core silently empties; heal them like the inbounds below.
+	// A pasted or restored template can still carry pre-#6258 XHTTP session keys, a pre-26.10.10
+	// xdns mask or a pre-26.9.9 quicParams.udpHop, all of which the core silently ignores.
 	xrayConfig.OutboundConfigs = healOutboundStreams(xrayConfig.OutboundConfigs,
-		liftXhttpSessionIDKeys, upgradeStreamLegacyXdns)
+		liftXhttpSessionIDKeys, upgradeStreamLegacyXdns, upgradeStreamLegacyUDPHop)
 	// Bridge amneziawg outbounds before anything else reads OutboundConfigs;
 	// the core has no amneziawg proxy and would reject the raw entry.
 	if err := transformAmneziaWGOutbounds(xrayConfig); err != nil {
@@ -1748,3 +1748,7 @@ func healOutboundStreams(raw json_util.RawMessage, heals ...func(stream map[stri
 func upgradeStreamLegacyXdns(stream map[string]any) bool {
 	return maskcompat.UpgradeLegacyXdns(stream["finalmask"])
 }
+
+func upgradeStreamLegacyUDPHop(stream map[string]any) bool {
+	return maskcompat.UpgradeLegacyUDPHop(stream["finalmask"])
+}