10 KiB
Routing Hook
The core calls the global HandleRoute function in routing.script when selecting an outbound. See the Routing Scripts guide for configuration and complete examples.
API Index
| Category | Member | Description |
|---|---|---|
| Hook | HandleRoute(...) |
Select an outbound for a request |
| Object | routing.Context |
The current request's routing context |
| Method | ctx:GetSourceIPs() |
Get source IPs |
| Method | ctx:GetTargetIPs() |
Get target IPs |
| Method | ctx:GetLocalIPs() |
Get local IPs |
| Method | ctx:GetAttributes() |
Get request attributes |
Hook Interface
HandleRoute(...)
function HandleRoute(ctx, inboundTag, sourcePort, targetPort,
localPort, targetDomain, network, protocol, user,
vlessRoute, skipDNSResolve)
return outboundTag, ruleTag, err
end
Selects an outbound for the current request, optionally returning a rule name or an error.
Parameters
The core always passes all 11 parameters in the order shown above, and none is nil. You can omit unused trailing parameters from the function definition; this does not change the values passed by the core.
| Parameter | Type | Description | Empty and Default Values |
|---|---|---|---|
ctx |
routing.Context |
Current request context | Always valid userdata |
inboundTag |
string |
Inbound tag | "" if the inbound has no tag or inbound information is unavailable |
sourcePort |
number |
Source port, 0 .. 65535 |
0 if no valid source address is available |
targetPort |
number |
Target port, 0 .. 65535 |
0 if no valid target address is available |
localPort |
number |
Local port of the inbound connection, 0 .. 65535 |
0 if no valid local address is available |
targetDomain |
string |
The effective sniffed domain takes precedence over the connection's target domain; converted to lowercase | "" if the target is an IP without an effective sniffed domain, or target information is unavailable |
network |
number |
Network type; compare with constants such as router.NetworkTCP |
NetworkUnknown (0) if outbound information is unavailable or the network type is unknown |
protocol |
string |
Sniffed protocol | "" if sniffed protocol information is unavailable |
user |
string |
User email | "" if inbound or user information is unavailable, or no email is set |
vlessRoute |
number |
Routing value formed from bytes 7 and 8 of the VLESS UUID, 0 .. 65535 |
0 if unavailable; the value itself may also be 0 |
skipDNSResolve |
boolean |
When true, DNS queries must be skipped to avoid loops |
false if the flag or additional request information is unavailable |
Return Values
| Return value | Type | Description |
|---|---|---|
outboundTag |
string or nil |
Outbound tag; nil or "" means no outbound was selected |
ruleTag |
string or nil |
Optional rule name; nil, omission, or "" means no name |
err |
error, string, or nil |
Only nil means no error |
Behavior
The core validates err, outboundTag, and ruleTag in that order, stopping at the first error. When err is non-nil, the first two values are ignored. When no outbound is selected, ruleTag is ignored.
On success, trailing ruleTag and err values may be omitted, for example return "direct". An error must be in the third position, for example return nil, nil, "routing failed"; return nil, "routing failed" does not report an error.
| Script result | Core behavior |
|---|---|
Validation succeeds and outboundTag is non-empty |
Uses the corresponding outbound; closes the connection if the tag does not exist |
| No outbound selected | Uses the default outbound |
| Returned error, invalid return-value type, or execution exception | Logs the error and tries the default outbound |
The default outbound is the first outbound in the configuration; the connection is closed if no default outbound is available. To block traffic, explicitly return a configured blackhole outbound tag instead of relying on this behavior with a nonexistent tag.
Related Objects
routing.Context
routing.Context represents the current request's routing context, accessed through the ctx parameter in HandleRoute.
| Property | Description |
|---|---|
| Underlying Go type | The routing.Context interface in features/routing |
| Lua representation | userdata |
| Obtained from | The first argument passed by the core to HandleRoute |
All methods below take no additional parameters. See Data Types for IP and slice operations.
GetSourceIPs
local ips = ctx:GetSourceIPs()
Gets the request's source IPs.
Parameters
No additional parameters.
Return Values
| Return value | Type | Description |
|---|---|---|
ips |
[]net.IP or nil |
IP list for the corresponding address |
Behavior
Returns nil if there is no inbound, the source address is invalid, or it is not an IP address.
GetTargetIPs
local ips = ctx:GetTargetIPs()
Gets the request's target IPs.
Parameters
No additional parameters.
Return Values
| Return value | Type | Description |
|---|---|---|
ips |
[]net.IP or nil |
IP list for the corresponding address |
Behavior
Returns nil if there is no outbound, the target address is invalid, or it is a domain name.
GetLocalIPs
local ips = ctx:GetLocalIPs()
Gets the local IPs of the inbound connection.
Parameters
No additional parameters.
Return Values
| Return value | Type | Description |
|---|---|---|
ips |
[]net.IP or nil |
IP list for the corresponding address |
Behavior
Returns nil if there is no inbound, the local address is invalid, or it is not an IP address.
GetAttributes
local attributes = ctx:GetAttributes()
Gets the current request's attributes.
Parameters
No additional parameters.
Return Values
| Return value | Type | Description |
|---|---|---|
attributes |
map[string]string |
Always userdata; never nil |
Behavior
Read attributes with attributes[key], where key must be a string. An existing key returns a string (possibly ""); a missing key returns nil.
See the attrs field in the routing configuration for the meaning and use of attributes.
Example
local attributes = ctx:GetAttributes()
if attributes[":method"] == "GET" then
return "direct", "lua-get"
end