Xray-core: Add Lua script for dns and routing (#6823)

https://github.com/XTLS/Xray-core/pull/6823#issuecomment-5843754759
https://github.com/XTLS/Xray-core/pull/6823#issuecomment-5861456450
https://github.com/XTLS/Xray-core/pull/6823#issuecomment-6093596069

app/router/config.pb.go

@@ -587,8 +587,10 @@ type Config struct {
 	DomainStrategy Config_DomainStrategy  `protobuf:"varint,1,opt,name=domain_strategy,json=domainStrategy,proto3,enum=xray.app.router.Config_DomainStrategy" json:"domain_strategy,omitempty"`
 	Rule           []*RoutingRule         `protobuf:"bytes,2,rep,name=rule,proto3" json:"rule,omitempty"`
 	BalancingRule  []*BalancingRule       `protobuf:"bytes,3,rep,name=balancing_rule,json=balancingRule,proto3" json:"balancing_rule,omitempty"`
-	unknownFields  protoimpl.UnknownFields
-	sizeCache      protoimpl.SizeCache
+	// Absolute path to the Lua routing script.
+	Script        string `protobuf:"bytes,4,opt,name=script,proto3" json:"script,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
 }
 
 func (x *Config) Reset() {
@@ -642,6 +644,13 @@ func (x *Config) GetBalancingRule() []*BalancingRule {
 	return nil
 }
 
+func (x *Config) GetScript() string {
+	if x != nil {
+		return x.Script
+	}
+	return ""
+}
+
 var File_app_router_config_proto protoreflect.FileDescriptor
 
 const file_app_router_config_proto_rawDesc = "" +
@@ -699,11 +708,12 @@ const file_app_router_config_proto_rawDesc = "" +
 	"\tbaselines\x18\x03 \x03(\x03R\tbaselines\x12\x1a\n" +
 	"\bexpected\x18\x04 \x01(\x05R\bexpected\x12\x16\n" +
 	"\x06maxRTT\x18\x05 \x01(\x03R\x06maxRTT\x12\x1c\n" +
-	"\ttolerance\x18\x06 \x01(\x02R\ttolerance\"\x96\x02\n" +
+	"\ttolerance\x18\x06 \x01(\x02R\ttolerance\"\xae\x02\n" +
 	"\x06Config\x12O\n" +
 	"\x0fdomain_strategy\x18\x01 \x01(\x0e2&.xray.app.router.Config.DomainStrategyR\x0edomainStrategy\x120\n" +
 	"\x04rule\x18\x02 \x03(\v2\x1c.xray.app.router.RoutingRuleR\x04rule\x12E\n" +
-	"\x0ebalancing_rule\x18\x03 \x03(\v2\x1e.xray.app.router.BalancingRuleR\rbalancingRule\"B\n" +
+	"\x0ebalancing_rule\x18\x03 \x03(\v2\x1e.xray.app.router.BalancingRuleR\rbalancingRule\x12\x16\n" +
+	"\x06script\x18\x04 \x01(\tR\x06script\"B\n" +
 	"\x0eDomainStrategy\x12\b\n" +
 	"\x04AsIs\x10\x00\x12\x10\n" +
 	"\fIpIfNonMatch\x10\x02\x12\x0e\n" +

app/router/config.proto

@@ -110,4 +110,6 @@ message Config {
   DomainStrategy domain_strategy = 1;
   repeated RoutingRule rule = 2;
   repeated BalancingRule balancing_rule = 3;
+  // Absolute path to the Lua routing script.
+  string script = 4;
 }

app/router/lua.go

@@ -0,0 +1,175 @@
+package router
+
+import (
+	"runtime"
+	"strings"
+
+	"github.com/xtls/xray-core/common/errors"
+	xlua "github.com/xtls/xray-core/common/lua"
+	"github.com/xtls/xray-core/common/net"
+	"github.com/xtls/xray-core/features/routing"
+	lua "github.com/yuin/gopher-lua"
+)
+
+const (
+	luaContextType    = "xray.router.Context"
+	luaAttributesType = "xray.router.Attributes"
+)
+
+// RegisterLua makes xray.router available to routing scripts.
+func (r *Router) RegisterLua(L *lua.LState) {
+	registerLuaContext(L)
+
+	L.PreloadModule("xray.router", func(L *lua.LState) int {
+		module := L.CreateTable(0, 7)
+
+		module.RawSetString("NetworkUnknown", lua.LNumber(net.Network_Unknown))
+		module.RawSetString("NetworkTCP", lua.LNumber(net.Network_TCP))
+		module.RawSetString("NetworkUDP", lua.LNumber(net.Network_UDP))
+		module.RawSetString("NetworkUNIX", lua.LNumber(net.Network_UNIX))
+		module.RawSetString("LocalOS", lua.LString(runtime.GOOS))
+
+		module.RawSetString("PickOutbound", L.NewFunction(func(L *lua.LState) int {
+			tag, ok := L.Get(2).(lua.LString)
+			if !ok {
+				L.ArgError(2, "balancer tag must be a string")
+				return 0
+			}
+			balancer, found := (*r.balancers.Load())[string(tag)]
+			if !found {
+				xlua.PushNil(L)
+				xlua.PushError(L, errors.New("balancer ", tag, " not found"))
+				return 2
+			}
+			outboundTag, err := balancer.PickOutbound()
+			xlua.PushString(L, outboundTag)
+			xlua.PushError(L, err)
+			return 2
+		}))
+
+		module.RawSetString("FindProcess", L.NewFunction(func(L *lua.LState) int {
+			pid, name, path, err := findProcess(checkLuaContext(L), net.FindProcess)
+			xlua.PushNumber(L, pid)
+			xlua.PushString(L, name)
+			xlua.PushString(L, path)
+			xlua.PushError(L, err)
+			return 4
+		}))
+
+		L.Push(module)
+		return 1
+	})
+}
+
+func registerLuaContext(L *lua.LState) {
+	pushIPs := xlua.NewSlicePusher[net.IP](L)
+	attributes := L.NewTypeMetatable(luaAttributesType)
+	L.SetField(attributes, "__index", L.NewFunction(func(L *lua.LState) int {
+		values := L.CheckUserData(1).Value.(map[string]string)
+		key := L.CheckString(2)
+		if value, found := values[key]; found {
+			xlua.PushString(L, value)
+		} else {
+			xlua.PushNil(L)
+		}
+		return 1
+	}))
+	methods := L.CreateTable(0, 4)
+	L.SetFuncs(methods, map[string]lua.LGFunction{
+		"GetSourceIPs": func(L *lua.LState) int {
+			pushIPs(L, checkLuaContext(L).GetSourceIPs())
+			return 1
+		},
+		"GetTargetIPs": func(L *lua.LState) int {
+			pushIPs(L, checkLuaContext(L).GetTargetIPs())
+			return 1
+		},
+		"GetLocalIPs": func(L *lua.LState) int {
+			pushIPs(L, checkLuaContext(L).GetLocalIPs())
+			return 1
+		},
+		"GetAttributes": func(L *lua.LState) int {
+			values := L.NewUserData()
+			values.Value = checkLuaContext(L).GetAttributes()
+			L.SetMetatable(values, attributes)
+			L.Push(values)
+			return 1
+		},
+	})
+	L.SetField(L.NewTypeMetatable(luaContextType), "__index", methods)
+}
+
+func checkLuaContext(L *lua.LState) routing.Context {
+	ctx, ok := L.CheckUserData(1).Value.(routing.Context)
+	if !ok {
+		L.ArgError(1, "routing context expected")
+	}
+	return ctx
+}
+
+// callLuaRoute runs HandleRoute and leaves (outboundTag, ruleTag, err) on the stack.
+func callLuaRoute(L *lua.LState, ctx routing.Context) error {
+	fn := L.GetGlobal("HandleRoute")
+	if fn.Type() != lua.LTFunction {
+		return errors.New("routing script must define HandleRoute(...)")
+	}
+
+	value := L.NewUserData()
+	value.Value = ctx
+	L.SetMetatable(value, L.GetTypeMetatable(luaContextType))
+
+	return L.CallByParam(lua.P{Fn: fn, NRet: 3, Protect: true},
+		value,
+		lua.LString(ctx.GetInboundTag()),
+		lua.LNumber(ctx.GetSourcePort()),
+		lua.LNumber(ctx.GetTargetPort()),
+		lua.LNumber(ctx.GetLocalPort()),
+		lua.LString(strings.ToLower(ctx.GetTargetDomain())),
+		lua.LNumber(ctx.GetNetwork()),
+		lua.LString(ctx.GetProtocol()),
+		lua.LString(ctx.GetUser()),
+		lua.LNumber(ctx.GetVlessRoute()),
+		lua.LBool(ctx.GetSkipDNSResolve()))
+}
+
+// readLuaRouteResult reads (outboundTag, ruleTag, err) from the stack.
+func readLuaRouteResult(L *lua.LState) (string, string, error) {
+	if err := xlua.ReadError(L.Get(-1), "routing script error must be an error or string"); err != nil {
+		return "", "", err
+	}
+
+	outboundTag, err := xlua.ReadOptionalString(L.Get(-3), "routing script outboundTag must be a string or nil")
+	if err != nil || outboundTag == "" {
+		return "", "", err
+	}
+
+	ruleTag, err := xlua.ReadOptionalString(L.Get(-2), "routing script ruleTag must be a string")
+	if err != nil {
+		return "", "", err
+	}
+
+	return outboundTag, ruleTag, nil
+}
+
+type processFinder func(string, string, uint16, string, uint16) (int, string, string, error)
+
+func findProcess(ctx routing.Context, finder processFinder) (int, string, string, error) {
+	sources := ctx.GetSourceIPs()
+	if len(sources) == 0 {
+		return 0, "", "", errors.New("process lookup requires a source IP")
+	}
+	var network string
+	switch ctx.GetNetwork() {
+	case net.Network_TCP:
+		network = "tcp"
+	case net.Network_UDP:
+		network = "udp"
+	default:
+		return 0, "", "", errors.New("process lookup requires TCP or UDP")
+	}
+	targetIP, targetPort := "", uint16(0)
+	if targets := ctx.GetTargetIPs(); len(targets) > 0 {
+		targetIP, targetPort = targets[0].String(), uint16(ctx.GetTargetPort())
+	}
+	return finder(network, sources[0].String(), uint16(ctx.GetSourcePort()), targetIP, targetPort)
+}

app/router/lua_benchmark_test.go

@@ -0,0 +1,223 @@
+package router
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/xtls/xray-core/common/geodata"
+	"github.com/xtls/xray-core/common/net"
+	"github.com/xtls/xray-core/common/session"
+	"github.com/xtls/xray-core/features/routing"
+	routing_session "github.com/xtls/xray-core/features/routing/session"
+	lua "github.com/yuin/gopher-lua"
+)
+
+func benchmarkRouteContext(target net.Destination) *routing_session.Context {
+	// Use the production context: its IP getters construct a slice per call.
+	// The cached IP slices in luaRouteTestContext would undercount this cost.
+	return &routing_session.Context{
+		Inbound: &session.Inbound{
+			Tag:    "in",
+			Source: net.TCPDestination(net.LocalHostIP, 1234),
+			Local:  net.TCPDestination(net.LocalHostIP, 5678),
+		},
+		Outbound: &session.Outbound{Target: target},
+		Content:  &session.Content{Protocol: "tls"},
+	}
+}
+
+func benchmarkRouteState(b *testing.B, r *Router, script string) *lua.LState {
+	b.Helper()
+	L := lua.NewState()
+	b.Cleanup(L.Close)
+	r.RegisterLua(L)
+	geodata.RegisterLua(L)
+	if err := L.DoString(script); err != nil {
+		b.Fatal(err)
+	}
+	L.SetContext(context.Background())
+	return L
+}
+
+// BenchmarkLuaRouteHook isolates argument bridging and a fixed-return hook.
+// It excludes rules, result decoding, the state pool, and Route construction.
+func BenchmarkLuaRouteHook(b *testing.B) {
+	L := benchmarkRouteState(b, new(Router), `
+function HandleRoute(ctx, inboundTag, sourcePort, targetPort, localPort,
+    targetDomain, network, protocol, user, vlessRoute, skipDNSResolve)
+    return "out", "rule"
+end
+`)
+	ctx := benchmarkRouteContext(net.TCPDestination(net.LocalHostIP, 443))
+	if err := callLuaRoute(L, ctx); err != nil {
+		b.Fatal(err)
+	}
+	outboundTag, ruleTag, err := readLuaRouteResult(L)
+	L.Pop(3)
+	if err != nil || outboundTag != "out" || ruleTag != "rule" {
+		b.Fatalf("hook() = %q, %q, %v", outboundTag, ruleTag, err)
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if err := callLuaRoute(L, ctx); err != nil {
+			b.Fatal(err)
+		}
+		L.Pop(3)
+	}
+}
+
+// BenchmarkLuaRoute compares equivalent ordered rules on the same session.
+// rules returns tags only; pick_route uses Router.PickRoute on both sides.
+// All compilation, matcher construction, and pool startup are outside timing.
+func BenchmarkLuaRoute(b *testing.B) {
+	for _, name := range []string{"scalar", "ip", "domain", "domain_32_last"} {
+		b.Run(name, func(b *testing.B) {
+			config, script, ctx, wantTag, wantRule := benchmarkRouteFixture(b, name)
+			native := new(Router)
+			if err := native.Init(context.Background(), config, nil, nil, nil); err != nil {
+				b.Fatal(err)
+			}
+			L := benchmarkRouteState(b, native, script)
+
+			path := filepath.Join(b.TempDir(), "route.lua")
+			if err := os.WriteFile(path, []byte(script), 0o600); err != nil {
+				b.Fatal(err)
+			}
+			scripted := new(Router)
+			if err := scripted.Init(context.Background(), &Config{Script: path}, nil, nil, nil); err != nil {
+				b.Fatal(err)
+			}
+			if err := scripted.Start(); err != nil {
+				b.Fatal(err)
+			}
+			b.Cleanup(func() {
+				if err := scripted.Close(); err != nil {
+					b.Error(err)
+				}
+			})
+
+			for _, bench := range []struct {
+				name  string
+				route func() (string, string, error)
+			}{
+				{"rules/native", func() (string, string, error) {
+					rule, _, err := native.pickRouteInternal(ctx)
+					if err != nil {
+						return "", "", err
+					}
+					tag, err := rule.GetTag()
+					return tag, rule.RuleTag, err
+				}},
+				{"rules/lua", func() (string, string, error) {
+					if err := callLuaRoute(L, ctx); err != nil {
+						return "", "", err
+					}
+					tag, ruleTag, err := readLuaRouteResult(L)
+					L.Pop(3)
+					return tag, ruleTag, err
+				}},
+				{"pick_route/native", func() (string, string, error) {
+					return benchmarkPickRoute(native, ctx)
+				}},
+				{"pick_route/lua", func() (string, string, error) {
+					return benchmarkPickRoute(scripted, ctx)
+				}},
+			} {
+				b.Run(bench.name, func(b *testing.B) {
+					// Validate and warm both paths before measuring steady state.
+					tag, ruleTag, err := bench.route()
+					if err != nil || tag != wantTag || ruleTag != wantRule {
+						b.Fatalf("route() = %q, %q, %v; want %q, %q", tag, ruleTag, err, wantTag, wantRule)
+					}
+					b.ReportAllocs()
+					b.ResetTimer()
+					for i := 0; i < b.N; i++ {
+						tag, ruleTag, err = bench.route()
+						if err != nil {
+							b.Fatal(err)
+						}
+					}
+					b.StopTimer()
+					if tag != wantTag || ruleTag != wantRule {
+						b.Fatalf("route() = %q, %q; want %q, %q", tag, ruleTag, wantTag, wantRule)
+					}
+				})
+			}
+		})
+	}
+}
+
+func benchmarkPickRoute(r *Router, ctx routing.Context) (string, string, error) {
+	route, err := r.PickRoute(ctx)
+	if err != nil {
+		return "", "", err
+	}
+	return route.GetOutboundTag(), route.GetRuleTag(), nil
+}
+
+func benchmarkRouteFixture(b *testing.B, name string) (*Config, string, routing.Context, string, string) {
+	b.Helper()
+	config := new(Config)
+	ctx := benchmarkRouteContext(net.TCPDestination(net.LocalHostIP, 443))
+	prelude := `local router = require("xray.router")
+local geodata = require("xray.geodata")
+`
+	body := `if inboundTag == "in" and network == router.NetworkTCP then return "out", "rule" end`
+	wantTag, wantRule := "out", "rule"
+	if name == "scalar" || name == "ip" {
+		rule := &RoutingRule{
+			TargetTag:  &RoutingRule_Tag{Tag: wantTag},
+			RuleTag:    wantRule,
+			InboundTag: []string{"in"},
+			Networks:   []net.Network{net.Network_TCP},
+		}
+		if name == "ip" {
+			var err error
+			rule.Ip, err = geodata.ParseIPRules([]string{"127.0.0.0/8"})
+			if err != nil {
+				b.Fatal(err)
+			}
+			prelude += `local matcher = geodata.BuildIPMatcher("127.0.0.0/8")` + "\n"
+			body = `if inboundTag == "in" and network == router.NetworkTCP and matcher:AnyMatch(ctx:GetTargetIPs()) then return "out", "rule" end`
+		}
+		config.Rule = []*RoutingRule{rule}
+	} else {
+		count := 1
+		if name == "domain_32_last" {
+			count = 32
+		}
+		var rules strings.Builder
+		rules.WriteString("local rules = {\n")
+		for i := 0; i < count; i++ {
+			domain := fmt.Sprintf("route-%d.example.com", i)
+			tag, ruleTag := fmt.Sprintf("out-%d", i), fmt.Sprintf("rule-%d", i)
+			domains, err := geodata.ParseDomainRules([]string{"full:" + domain}, geodata.Domain_Domain)
+			if err != nil {
+				b.Fatal(err)
+			}
+			config.Rule = append(config.Rule, &RoutingRule{
+				TargetTag: &RoutingRule_Tag{Tag: tag}, RuleTag: ruleTag, Domain: domains,
+			})
+			fmt.Fprintf(&rules, "{geodata.BuildDomainMatcher(%q), %q, %q},\n", "full:"+domain, tag, ruleTag)
+			if i == count-1 {
+				ctx.Outbound.Target = net.TCPDestination(net.DomainAddress(domain), 443)
+				wantTag, wantRule = tag, ruleTag
+			}
+		}
+		rules.WriteString("}\n")
+		prelude += rules.String()
+		body = `for i = 1, #rules do
+        local rule = rules[i]
+        if rule[1]:MatchAny(targetDomain) then return rule[2], rule[3] end
+    end`
+	}
+	script := prelude + `function HandleRoute(ctx, inboundTag, sourcePort, targetPort, localPort,
+    targetDomain, network, protocol, user, vlessRoute, skipDNSResolve)
+    ` + body + "\nend\n"
+	return config, script, ctx, wantTag, wantRule
+}

app/router/lua_test.go

@@ -0,0 +1,274 @@
+package router
+
+import (
+	"context"
+	go_errors "errors"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/xtls/xray-core/common/geodata"
+	"github.com/xtls/xray-core/common/net"
+	"github.com/xtls/xray-core/common/protocol"
+	"github.com/xtls/xray-core/common/session"
+	"github.com/xtls/xray-core/features/routing"
+	routing_session "github.com/xtls/xray-core/features/routing/session"
+	lua "github.com/yuin/gopher-lua"
+)
+
+type luaRouteTestContext struct {
+	*routing_session.Context
+	sourceIPs, targetIPs, localIPs []net.IP
+}
+
+func (c *luaRouteTestContext) GetSourceIPs() []net.IP { return c.sourceIPs }
+func (c *luaRouteTestContext) GetTargetIPs() []net.IP { return c.targetIPs }
+func (c *luaRouteTestContext) GetLocalIPs() []net.IP  { return c.localIPs }
+
+func newLuaRouteTestContext() *luaRouteTestContext {
+	return &luaRouteTestContext{
+		Context: &routing_session.Context{
+			Inbound: &session.Inbound{
+				Tag: "in", VlessRoute: 4321,
+				Source: net.TCPDestination(net.LocalHostIP, 1234),
+				Local:  net.TCPDestination(net.LocalHostIP, 5678),
+				User:   &protocol.MemoryUser{Email: "user@example.com"},
+			},
+			Outbound: &session.Outbound{
+				Target:      net.TCPDestination(net.LocalHostIP, 443),
+				RouteTarget: net.TCPDestination(net.DomainAddress("MiXeD.Example."), 443),
+			},
+			Content: &session.Content{
+				Protocol: "tls", Attributes: map[string]string{"key": "value"}, SkipDNSResolve: true,
+			},
+		},
+		sourceIPs: []net.IP{{127, 0, 0, 2}},
+		targetIPs: []net.IP{{127, 0, 0, 3}},
+		localIPs:  []net.IP{{127, 0, 0, 1}},
+	}
+}
+
+func newLuaRouterState(t *testing.T, script string) *lua.LState {
+	t.Helper()
+	r := new(Router)
+	if err := r.Init(context.Background(), &Config{}, nil, nil, nil); err != nil {
+		t.Fatal(err)
+	}
+	L := lua.NewState()
+	t.Cleanup(L.Close)
+	r.RegisterLua(L)
+	geodata.RegisterLua(L)
+	if err := L.DoString(script); err != nil {
+		t.Fatal(err)
+	}
+	return L
+}
+
+func TestLuaRouteBinding(t *testing.T) {
+	L := newLuaRouterState(t, `
+local router = require("xray.router")
+local matcher = require("xray.geodata").BuildIPMatcher("127.0.0.0/8")
+assert(router.NetworkUnknown == 0 and router.NetworkTCP == 2)
+assert(router.NetworkUDP == 3 and router.NetworkUNIX == 4)
+assert(router.BuildIPMatcher == nil and router.BuildDomainMatcher == nil)
+function HandleRoute(ctx, inboundTag, sourcePort, targetPort, localPort,
+    targetDomain, network, protocol, user, vlessRoute, skipDNSResolve, ...)
+    assert(select("#", ...) == 0)
+    assert(inboundTag == "in" and sourcePort == 1234 and targetPort == 443 and localPort == 5678)
+    assert(targetDomain == "mixed.example." and network == router.NetworkTCP)
+    assert(protocol == "tls" and user == "user@example.com" and vlessRoute == 4321 and skipDNSResolve)
+    assert(ctx.GetNetwork == nil and ctx.Context == nil)
+    savedContext = ctx
+    sourceIPs, targetIPs, localIPs = ctx:GetSourceIPs(), ctx:GetTargetIPs(), ctx:GetLocalIPs()
+    attributes = ctx:GetAttributes()
+    assert(#sourceIPs == 1 and #targetIPs == 1 and #localIPs == 1)
+    assert(sourceIPs[1]:String() == "127.0.0.2" and targetIPs[1]:String() == "127.0.0.3")
+    assert(localIPs[1]:String() == "127.0.0.1")
+    assert(matcher:Match(sourceIPs[1]) and matcher:Match(targetIPs[1]) and matcher:Match(localIPs[1]))
+    assert(matcher:AnyMatch(sourceIPs) and matcher:AnyMatch(targetIPs) and matcher:AnyMatch(localIPs))
+    local matched = matcher:FilterIPs(targetIPs)
+    assert(#matched == 1 and matched[1]:Equal(targetIPs[1]))
+    assert(attributes.key == "value" and attributes.missing == nil)
+    assert(not pcall(function() attributes.key = "changed" end))
+    return "out", "rule"
+end`)
+
+	ctx := newLuaRouteTestContext()
+	if err := callLuaRoute(L, ctx); err != nil {
+		t.Fatal(err)
+	}
+	if L.GetTop() != 3 || L.Get(1) != lua.LString("out") || L.Get(2) != lua.LString("rule") || L.Get(3) != lua.LNil {
+		t.Fatal("callLuaRoute did not leave the three route results on the stack")
+	}
+	if L.GetGlobal("savedContext").(*lua.LUserData).Value != ctx {
+		t.Fatal("routing context was copied")
+	}
+	for _, tc := range []struct {
+		name string
+		want []net.IP
+	}{
+		{"sourceIPs", ctx.sourceIPs},
+		{"targetIPs", ctx.targetIPs},
+		{"localIPs", ctx.localIPs},
+	} {
+		got := L.GetGlobal(tc.name).(*lua.LUserData).Value.([]net.IP)
+		if &got[0] != &tc.want[0] {
+			t.Fatalf("%s storage was copied", tc.name)
+		}
+	}
+	ctx.Content.Attributes["key"] = "updated"
+	L.SetGlobal("expectedOS", lua.LString(runtime.GOOS))
+	if err := L.DoString(`
+assert(attributes.key == "updated")
+assert(require("xray.router").LocalOS == expectedOS)`); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestLuaRouteEmptyIPs(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		ips  []net.IP
+	}{
+		{"nil", nil},
+		{"empty", []net.IP{}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			L := newLuaRouterState(t, `
+function HandleRoute(ctx)
+    for _, name in ipairs({"GetSourceIPs", "GetTargetIPs", "GetLocalIPs"}) do
+        local ips = ctx[name](ctx)
+        if expectNil then
+            assert(ips == nil)
+        else
+            assert(type(ips) == "userdata" and #ips == 0)
+            assert(not pcall(function() return ips[1] end))
+        end
+    end
+    return "out"
+end
+`)
+			L.SetGlobal("expectNil", lua.LBool(tc.ips == nil))
+			ctx := newLuaRouteTestContext()
+			ctx.sourceIPs, ctx.targetIPs, ctx.localIPs = tc.ips, tc.ips, tc.ips
+			if err := callLuaRoute(L, ctx); err != nil {
+				t.Fatal(err)
+			}
+		})
+	}
+}
+
+func TestReadLuaRouteResult(t *testing.T) {
+	nativeErr := go_errors.New("native failure")
+	for _, tc := range []struct {
+		name, values      string
+		wantTag, wantRule string
+		wantErr           error
+		wantMessage       string
+	}{
+		{name: "route", values: `"out", "rule"`, wantTag: "out", wantRule: "rule"},
+		{name: "no match", values: `nil`},
+		{name: "empty tag", values: `""`},
+		{name: "no match ignores rule", values: `nil, false`},
+		{name: "empty tag ignores rule", values: `"", false`},
+		{name: "missing rule", values: `"out"`, wantTag: "out"},
+		{name: "invalid tag", values: `1`, wantMessage: "outboundTag"},
+		{name: "invalid rule", values: `"out", false`, wantMessage: "ruleTag"},
+		{name: "string error", values: `nil, nil, "script failure"`, wantMessage: "script failure"},
+		{name: "native error", values: `nil, nil, nativeError`, wantErr: nativeErr},
+		{name: "error overrides invalid tags", values: `false, false, nativeError`, wantErr: nativeErr},
+		{name: "invalid error", values: `"out", "rule", false`, wantMessage: "error or string"},
+		{name: "wrong error userdata", values: `"out", "rule", wrongError`, wantMessage: "error or string"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			L := lua.NewState()
+			defer L.Close()
+			for name, value := range map[string]any{"nativeError": nativeErr, "wrongError": "not a native error"} {
+				ud := L.NewUserData()
+				ud.Value = value
+				L.SetGlobal(name, ud)
+			}
+			fn, err := L.LoadString("return " + tc.values)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := L.CallByParam(lua.P{Fn: fn, NRet: 3, Protect: true}); err != nil {
+				t.Fatal(err)
+			}
+			outboundTag, ruleTag, err := readLuaRouteResult(L)
+			if outboundTag != tc.wantTag || ruleTag != tc.wantRule {
+				t.Fatalf("result = %q, %q, %v; want %q, %q", outboundTag, ruleTag, err, tc.wantTag, tc.wantRule)
+			}
+			switch {
+			case tc.wantErr != nil:
+				if err != tc.wantErr {
+					t.Fatalf("error = %v, want original error", err)
+				}
+			case tc.wantMessage != "":
+				if err == nil || !strings.Contains(err.Error(), tc.wantMessage) {
+					t.Fatalf("error = %v, want %q", err, tc.wantMessage)
+				}
+			case err != nil:
+				t.Fatal(err)
+			}
+		})
+	}
+}
+
+func TestCallLuaRouteCancellation(t *testing.T) {
+	L := newLuaRouterState(t, `function HandleRoute() while true do end end`)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	L.SetContext(ctx)
+	if err := callLuaRoute(L, &routing_session.Context{}); err == nil {
+		t.Fatal("callLuaRoute did not stop after context cancellation")
+	}
+	if L.Context() != ctx {
+		t.Fatal("callLuaRoute changed the Lua state's context")
+	}
+}
+
+func TestFindProcess(t *testing.T) {
+	for _, tc := range []struct {
+		name, network, target string
+		targetPort            uint16
+		modify                func(*luaRouteTestContext)
+		wantErr               bool
+	}{
+		{name: "TCP", network: "tcp", target: "127.0.0.3", targetPort: 443},
+		{name: "UDP", network: "udp", target: "127.0.0.3", targetPort: 443, modify: func(c *luaRouteTestContext) {
+			c.Outbound.Target.Network = net.Network_UDP
+		}},
+		{name: "domain target", network: "tcp", modify: func(c *luaRouteTestContext) { c.targetIPs = nil }},
+		{name: "missing source", modify: func(c *luaRouteTestContext) { c.sourceIPs = nil }, wantErr: true},
+		{name: "unsupported network", modify: func(c *luaRouteTestContext) {
+			c.Outbound.Target.Network = net.Network_UNIX
+		}, wantErr: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			ctx := newLuaRouteTestContext()
+			if tc.modify != nil {
+				tc.modify(ctx)
+			}
+			called := false
+			pid, name, path, err := findProcess(ctx, func(network, source string, sourcePort uint16, target string, targetPort uint16) (int, string, string, error) {
+				called = true
+				if network != tc.network || source != "127.0.0.2" || sourcePort != 1234 || target != tc.target || targetPort != tc.targetPort {
+					t.Fatalf("endpoints = %s %s:%d -> %s:%d", network, source, sourcePort, target, targetPort)
+				}
+				return 42, "process", "/path/process", nil
+			})
+			if tc.wantErr {
+				if err == nil || called {
+					t.Fatalf("findProcess = %d, %q, %q, %v", pid, name, path, err)
+				}
+				return
+			}
+			if err != nil || !called || pid != 42 || name != "process" || path != "/path/process" {
+				t.Fatalf("findProcess = %d, %q, %q, %v", pid, name, path, err)
+			}
+		})
+	}
+}
+
+var _ routing.Context = (*luaRouteTestContext)(nil)

app/router/router.go

@@ -20,6 +20,8 @@ import (
 type Router struct {
 	domainStrategy Config_DomainStrategy
 	rules          atomic.Pointer[[]*Rule]
+	scriptPath     string
+	script         *scriptEngine
 	balancers      atomic.Pointer[map[string]*Balancer]
 	dns            dns.Client
 
@@ -40,6 +42,7 @@ type Route struct {
 // Init initializes the Router.
 func (r *Router) Init(ctx context.Context, config *Config, d dns.Client, ohm outbound.Manager, dispatcher routing.Dispatcher) error {
 	r.domainStrategy = config.DomainStrategy
+	r.scriptPath = config.Script
 	r.dns = d
 	r.ctx = ctx
 	r.ohm = ohm
@@ -52,6 +55,10 @@ func (r *Router) Init(ctx context.Context, config *Config, d dns.Client, ohm out
 
 // PickRoute implements routing.Router.
 func (r *Router) PickRoute(ctx routing.Context) (routing.Route, error) {
+	if r.script != nil {
+		return r.script.pickRoute(ctx)
+	}
+
 	originalCtx := ctx
 	rule, ctx, err := r.pickRouteInternal(ctx)
 	if err != nil {
@@ -221,6 +228,13 @@ func (r *Router) pickRouteInternal(ctx routing.Context) (*Rule, routing.Context,
 
 // Start implements common.Runnable.
 func (r *Router) Start() error {
+	if r.scriptPath != "" {
+		engine, err := newScriptEngine(r.scriptPath, r)
+		if err != nil {
+			return errors.New("failed to initialize routing script").Base(err)
+		}
+		r.script = engine
+	}
 	return nil
 }
 
@@ -235,6 +249,9 @@ func closeWebhooks(rules []*Rule) {
 
 // Close implements common.Closable.
 func (r *Router) Close() error {
+	if r.script != nil {
+		r.script.close()
+	}
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	closeWebhooks(*r.rules.Load())

app/router/script.go

@@ -0,0 +1,76 @@
+package router
+
+import (
+	"time"
+
+	"github.com/xtls/xray-core/app/dns"
+	"github.com/xtls/xray-core/common"
+	"github.com/xtls/xray-core/common/errors"
+	"github.com/xtls/xray-core/common/geodata"
+	"github.com/xtls/xray-core/common/log"
+	xlua "github.com/xtls/xray-core/common/lua"
+	"github.com/xtls/xray-core/features/routing"
+	lua "github.com/yuin/gopher-lua"
+)
+
+const scriptExecutionTimeout = 6 * time.Second
+
+type scriptEngine struct {
+	pool *xlua.Pool
+}
+
+func newScriptEngine(path string, router *Router) (*scriptEngine, error) {
+	program, err := xlua.CompileFile(path)
+	if err != nil {
+		return nil, err
+	}
+
+	pool, err := xlua.NewPool(router.ctx, scriptExecutionTimeout, program.NewStateFactory(
+		scriptExecutionTimeout*20,
+		func(L *lua.LState) {
+			geodata.RegisterLua(L)
+			log.RegisterLua(L)
+			router.RegisterLua(L)
+			dns.RegisterLua(L, router.dns)
+		},
+		func(L *lua.LState) error {
+			if L.GetGlobal("HandleRoute").Type() != lua.LTFunction {
+				return errors.New("routing script must define HandleRoute(...)")
+			}
+			return nil
+		}))
+	if err != nil {
+		return nil, err
+	}
+
+	errors.LogInfo(router.ctx, "routing script initialized from ", path)
+	return &scriptEngine{pool: pool}, nil
+}
+
+func (e *scriptEngine) close() {
+	e.pool.Close()
+}
+
+func (e *scriptEngine) pickRoute(ctx routing.Context) (routing.Route, error) {
+	var outboundTag, ruleTag string
+	var routeErr error
+
+	if err := e.pool.WithState(nil, 0, func(L *lua.LState) error {
+		if err := callLuaRoute(L, ctx); err != nil {
+			return err
+		}
+		outboundTag, ruleTag, routeErr = readLuaRouteResult(L)
+		return nil
+	}); err != nil {
+		return nil, err
+	}
+
+	if routeErr != nil {
+		return nil, routeErr
+	}
+	if outboundTag == "" {
+		return nil, common.ErrNoClue
+	}
+
+	return &Route{Context: ctx, outboundTag: outboundTag, ruleTag: ruleTag}, nil
+}

app/router/script_test.go

@@ -0,0 +1,382 @@
+package router
+
+import (
+	"context"
+	stdnet "net"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	wireDNS "github.com/miekg/dns"
+	"github.com/xtls/xray-core/app/dispatcher"
+	appdns "github.com/xtls/xray-core/app/dns"
+	"github.com/xtls/xray-core/app/proxyman"
+	_ "github.com/xtls/xray-core/app/proxyman/outbound"
+	"github.com/xtls/xray-core/common"
+	"github.com/xtls/xray-core/common/net"
+	"github.com/xtls/xray-core/common/serial"
+	"github.com/xtls/xray-core/core"
+	featureDNS "github.com/xtls/xray-core/features/dns"
+	"github.com/xtls/xray-core/features/outbound"
+	"github.com/xtls/xray-core/features/routing"
+	routing_session "github.com/xtls/xray-core/features/routing/session"
+	"github.com/xtls/xray-core/proxy/blackhole"
+	"github.com/xtls/xray-core/proxy/freedom"
+)
+
+type luaRouteDNSClient struct {
+	featureDNS.Client
+	lookup func(string, featureDNS.IPOption) ([]net.IP, uint32, error)
+}
+
+func (d *luaRouteDNSClient) LookupIP(domain string, option featureDNS.IPOption) ([]net.IP, uint32, error) {
+	return d.lookup(domain, option)
+}
+
+type luaRouteOutboundManager struct{ outbound.Manager }
+
+func (*luaRouteOutboundManager) Select(selectors []string) []string { return selectors }
+
+func writeRouteScript(t *testing.T, script string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "route.lua")
+	if err := os.WriteFile(path, []byte(script), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+func startLuaRouter(t *testing.T, script string, d featureDNS.Client, config *Config) *Router {
+	t.Helper()
+	if config == nil {
+		config = &Config{}
+	}
+	config.Script = writeRouteScript(t, script)
+	r := new(Router)
+	if err := r.Init(context.Background(), config, d, &luaRouteOutboundManager{}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.Start(); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := r.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	return r
+}
+
+func TestRouterScriptStartup(t *testing.T) {
+	for _, tc := range []struct{ name, script string }{
+		{"syntax error", "function HandleRoute("},
+		{"missing hook", "value = 1"},
+		{"initialization error", `error("setup failed")`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			r := new(Router)
+			if err := r.Init(context.Background(), &Config{Script: writeRouteScript(t, tc.script)}, nil, nil, nil); err != nil {
+				t.Fatal(err)
+			}
+			defer r.Close()
+			if err := r.Start(); err == nil {
+				t.Fatal("Start accepted an invalid routing script")
+			}
+		})
+	}
+}
+
+func TestRouterScriptRouting(t *testing.T) {
+	for _, tc := range []struct {
+		name, body        string
+		wantTag, wantRule string
+		wantErr           error
+		wantMessage       string
+		wantCalls         string
+	}{
+		{name: "route", body: `return "lua-out", "lua-rule"`, wantTag: "lua-out", wantRule: "lua-rule", wantCalls: "2"},
+		{name: "no match", body: `return nil`, wantErr: common.ErrNoClue, wantCalls: "2"},
+		{name: "empty tag", body: `return ""`, wantErr: common.ErrNoClue, wantCalls: "2"},
+		{name: "balancer error", body: `local tag, err = router:PickOutbound("missing"); return tag, nil, err`, wantMessage: "not found", wantCalls: "2"},
+		{name: "string error", body: `return nil, nil, "blocked"`, wantMessage: "blocked", wantCalls: "2"},
+		{name: "invalid tag", body: `return false`, wantMessage: "outboundTag", wantCalls: "2"},
+		{name: "invalid rule", body: `return "lua-out", false`, wantMessage: "ruleTag", wantCalls: "2"},
+		{name: "execution error", body: `error("execution failed")`, wantMessage: "execution failed", wantCalls: "1"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var dnsCalls atomic.Int32
+			d := &luaRouteDNSClient{lookup: func(string, featureDNS.IPOption) ([]net.IP, uint32, error) {
+				dnsCalls.Add(1)
+				return []net.IP{{1, 2, 3, 4}}, 60, nil
+			}}
+			script := `
+local router = require("xray.router")
+local calls = 0
+function HandleRoute(ctx, inbound)
+    calls = calls + 1
+    if inbound == "count" then return "lua-out", tostring(calls) end
+    ` + tc.body + `
+end
+`
+			r := startLuaRouter(t, script, d, &Config{
+				DomainStrategy: Config_IpOnDemand,
+				Rule: []*RoutingRule{{
+					TargetTag: &RoutingRule_Tag{Tag: "json-out"},
+					Networks:  []net.Network{net.Network_TCP},
+				}},
+			})
+			ctx := newLuaRouteTestContext()
+			ctx.Content.SkipDNSResolve = false
+			route, err := r.PickRoute(ctx)
+			switch {
+			case tc.wantErr != nil:
+				if err != tc.wantErr {
+					t.Fatalf("route error = %v, want %v", err, tc.wantErr)
+				}
+			case tc.wantMessage != "":
+				if err == nil || !strings.Contains(err.Error(), tc.wantMessage) {
+					t.Fatalf("route error = %v, want %q", err, tc.wantMessage)
+				}
+			case err != nil:
+				t.Fatal(err)
+			}
+			if tc.wantTag == "" {
+				if route != nil {
+					t.Fatalf("route = %v, want nil", route)
+				}
+			} else if route == nil || route.GetOutboundTag() != tc.wantTag || route.GetRuleTag() != tc.wantRule || route.(*Route).Context != ctx {
+				t.Fatalf("route = %v; want %q, %q and original context", route, tc.wantTag, tc.wantRule)
+			}
+
+			ctx.Inbound.Tag = "count"
+			route, err = r.PickRoute(ctx)
+			if err != nil || route == nil || route.GetOutboundTag() != "lua-out" || route.GetRuleTag() != tc.wantCalls {
+				t.Fatalf("next route = %v, %v; want lua-out, calls %s", route, err, tc.wantCalls)
+			}
+			if dnsCalls.Load() != 0 {
+				t.Fatal("script routing implicitly resolved DNS")
+			}
+		})
+	}
+}
+
+func TestRouterScriptModules(t *testing.T) {
+	ips := []net.IP{{127, 0, 0, 7}}
+	calls := 0
+	d := &luaRouteDNSClient{lookup: func(domain string, option featureDNS.IPOption) ([]net.IP, uint32, error) {
+		calls++
+		if domain != "mixed.example." || !option.IPv4Enable || option.IPv6Enable || !option.FakeEnable {
+			t.Fatalf("dns.Query arguments = %q, %+v", domain, option)
+		}
+		return ips, 17, nil
+	}}
+	r := startLuaRouter(t, `
+local dns = require("xray.dns")
+local matcher = require("xray.geodata").BuildIPMatcher("127.0.0.0/8")
+assert(dns.Servers == nil and type(dns.Query) == "function")
+assert(type(require("xray.log").Info) == "function")
+function HandleRoute(ctx, inbound, sourcePort, targetPort, localPort, domain)
+    local ips, ttl, err = dns.Query(domain, true, false, true)
+    assert(not err and ttl == 17)
+    assert(matcher:AnyMatch(ips) and matcher:AnyMatch(ctx:GetTargetIPs()))
+    return "out"
+end`, d, nil)
+	if _, err := r.PickRoute(newLuaRouteTestContext()); err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 {
+		t.Fatalf("DNS calls = %d, want 1", calls)
+	}
+}
+
+func TestRouterScriptBalancerReload(t *testing.T) {
+	config := func(tag string) *Config {
+		return &Config{BalancingRule: []*BalancingRule{{
+			Tag: "balance", Strategy: "roundrobin", OutboundSelector: []string{tag},
+		}}}
+	}
+	r := startLuaRouter(t, `
+local router = require("xray.router")
+function HandleRoute()
+    local tag, err = router:PickOutbound("balance")
+    return tag, "balanced", err
+end`, nil, config("old"))
+	pick := func(want string) {
+		t.Helper()
+		route, err := r.PickRoute(&routing_session.Context{})
+		if err != nil || route.GetOutboundTag() != want || route.GetRuleTag() != "balanced" {
+			t.Fatalf("route = %v, %v, want %q", route, err, want)
+		}
+	}
+
+	pick("old")
+	if err := r.SetOverrideTarget("balance", "override"); err != nil {
+		t.Fatal(err)
+	}
+	pick("override")
+	if err := r.SetOverrideTarget("balance", ""); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.ReloadRules(config("new"), false); err != nil {
+		t.Fatal(err)
+	}
+	pick("new")
+}
+
+func TestRouterScriptConcurrentBalancerReload(t *testing.T) {
+	config := func(tag string) *Config {
+		return &Config{BalancingRule: []*BalancingRule{{
+			Tag: "balance", Strategy: "roundrobin", OutboundSelector: []string{tag},
+		}}}
+	}
+	r := startLuaRouter(t, `
+local router = require("xray.router")
+function HandleRoute()
+    local tag, err = router:PickOutbound("balance")
+    return tag, nil, err
+end`, nil, config("a"))
+
+	var wg sync.WaitGroup
+	for range 4 {
+		wg.Go(func() {
+			for range 20 {
+				route, err := r.PickRoute(&routing_session.Context{})
+				if err != nil {
+					t.Errorf("PickRoute: %v", err)
+					return
+				}
+				if tag := route.GetOutboundTag(); tag != "a" && tag != "b" {
+					t.Errorf("unexpected tag %q", tag)
+				}
+			}
+		})
+	}
+	wg.Go(func() {
+		for range 20 {
+			for _, tag := range []string{"a", "b"} {
+				if err := r.ReloadRules(config(tag), false); err != nil {
+					t.Error(err)
+					return
+				}
+			}
+		}
+	})
+	wg.Wait()
+}
+
+func TestRouterScriptDNSDispatcherReentry(t *testing.T) {
+	conn, err := stdnet.ListenPacket("udp4", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	port := conn.LocalAddr().(*stdnet.UDPAddr).Port
+	ready, stopped := make(chan struct{}), make(chan error, 1)
+	var queries atomic.Int32
+	server := &wireDNS.Server{
+		PacketConn: conn,
+		NotifyStartedFunc: func() {
+			close(ready)
+		},
+		Handler: wireDNS.HandlerFunc(func(w wireDNS.ResponseWriter, query *wireDNS.Msg) {
+			queries.Add(1)
+			response := new(wireDNS.Msg).SetReply(query)
+			for _, question := range query.Question {
+				if question.Name == "nested.example." && question.Qtype == wireDNS.TypeA {
+					response.Answer = append(response.Answer, &wireDNS.A{
+						Hdr: wireDNS.RR_Header{Name: question.Name, Rrtype: wireDNS.TypeA, Class: wireDNS.ClassINET, Ttl: 60},
+						A:   stdnet.IP{127, 0, 0, 7},
+					})
+				}
+			}
+			if err := w.WriteMsg(response); err != nil {
+				t.Error(err)
+			}
+		}),
+	}
+	go func() { stopped <- server.ActivateAndServe() }()
+	defer func() {
+		server.Shutdown()
+		select {
+		case err := <-stopped:
+			if err != nil {
+				t.Error(err)
+			}
+		case <-time.After(3 * time.Second):
+			t.Error("DNS server did not stop")
+		}
+	}()
+	select {
+	case <-ready:
+	case err := <-stopped:
+		t.Fatalf("DNS server startup: %v", err)
+	case <-time.After(3 * time.Second):
+		t.Fatal("DNS server did not start")
+	}
+
+	dnsScript := writeRouteScript(t, `
+local server = require("xray.dns").Servers[1]
+function HandleDNSQuery(domain, ipv4, ipv6, fake)
+    return server:Query(domain, ipv4, ipv6, fake)
+end`)
+	routerScript := writeRouteScript(t, `
+local router = require("xray.router")
+local dns = require("xray.dns")
+local matcher = require("xray.geodata").BuildIPMatcher("127.0.0.7")
+local active = false
+function HandleRoute(ctx, inbound, sourcePort, targetPort, localPort, domain, network,
+    protocol, user, vlessRoute, skipDNSResolve)
+    assert(not active, "borrowed Router VM reentered")
+    if inbound == "dns" then
+        assert(network == router.NetworkUDP and skipDNSResolve == false)
+        return "direct", "dns-route"
+    end
+    active = true
+    local ips, ttl, err = dns.Query("nested.example", true, false, false)
+    assert(not err and matcher:AnyMatch(ips) and active)
+    active = false
+    return "direct", "outer-route"
+end`)
+	instance, err := core.New(&core.Config{
+		App: []*serial.TypedMessage{
+			serial.ToTypedMessage(&appdns.Config{
+				Tag: "dns", Script: dnsScript, DisableCache: true,
+				NameServer: []*appdns.NameServer{{
+					Id: "upstream", TimeoutMs: 1000,
+					Address: &net.Endpoint{
+						Network: net.Network_UDP,
+						Address: &net.IPOrDomain{Address: &net.IPOrDomain_Ip{Ip: []byte{127, 0, 0, 1}}},
+						Port:    uint32(port),
+					},
+				}},
+			}),
+			serial.ToTypedMessage(&Config{Script: routerScript}),
+			serial.ToTypedMessage(&dispatcher.Config{}),
+			serial.ToTypedMessage(&proxyman.OutboundConfig{}),
+		},
+		Outbound: []*core.OutboundHandlerConfig{
+			{Tag: "default", ProxySettings: serial.ToTypedMessage(&blackhole.Config{})},
+			{Tag: "direct", ProxySettings: serial.ToTypedMessage(&freedom.Config{
+				FinalRules: []*freedom.FinalRuleConfig{{Action: freedom.RuleAction_Allow}},
+			})},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer instance.Close()
+	if err := instance.Start(); err != nil {
+		t.Fatal(err)
+	}
+	r := instance.GetFeature(routing.RouterType()).(*Router)
+	route, err := r.PickRoute(newLuaRouteTestContext())
+	if err != nil || route.GetOutboundTag() != "direct" || route.GetRuleTag() != "outer-route" {
+		t.Fatalf("nested DNS routing = %v, %v", route, err)
+	}
+	if queries.Load() == 0 {
+		t.Fatal("DNS query did not pass through the dispatcher")
+	}
+}