6.5 KiB
xray.router
Provides constants and helpers for routing scripts. See Routing Hook for request parameters and context.
local router = require("xray.router")
API Index
| Category | Member | Description |
|---|---|---|
| Constant | router.NetworkUnknown |
Unknown network |
| Constant | router.NetworkTCP |
TCP |
| Constant | router.NetworkUDP |
UDP |
| Constant | router.NetworkUNIX |
UNIX |
| Constant | router.LocalOS |
Runtime platform |
| Function | router:PickOutbound(balancerTag) |
Select an outbound through a balancer |
| Function | router.FindProcess(ctx) |
Find the process associated with a local connection |
Constants
| Name | Type | Value / Description |
|---|---|---|
router.NetworkUnknown |
number |
0, unknown network |
router.NetworkTCP |
number |
2, TCP |
router.NetworkUDP |
number |
3, UDP |
router.NetworkUNIX |
number |
4, UNIX |
router.LocalOS |
string |
Current runtime platform, for example "windows", "linux", or "darwin" |
Compare the Routing Hook's network parameter with the network constants:
if network == router.NetworkUDP then
return "direct", "lua-udp"
end
Functions
router:PickOutbound
local outboundTag, err = router:PickOutbound(balancerTag)
Selects an outbound through the specified balancer.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
balancerTag |
string |
The tag of the balancer to use, configured in routing.balancers |
Return Values
| Return value | Type | Description |
|---|---|---|
outboundTag |
string or nil |
On success, the selected outbound's non-empty tag |
err |
error or nil |
nil indicates success |
Behavior
A string must be passed explicitly; otherwise a Lua exception is raised. An empty string "" looks up an empty tag.
Check err before using the result. If the balancer does not exist, returns nil, err; if it exists but selects no outbound, returns "", err. When the configured fallbackTag takes effect, returns that outbound tag and nil.
Example
The following uses the balancer with tag "proxy-pool" and passes on the result according to the Routing Hook's return-value convention:
local outboundTag, err = router:PickOutbound("proxy-pool")
return outboundTag, "lua-balance", err
See the Routing Scripts guide for a complete example.
router.FindProcess
local pid, name, path, err = router.FindProcess(ctx)
Finds the process on the local machine associated with the current connection.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
ctx |
routing.Context |
Current request context, passed to the Routing Hook |
Return Values
| Return value | Type | Description |
|---|---|---|
pid |
number |
Process ID; usually 0 if unavailable |
name |
string |
Process name; "" if unavailable |
path |
string |
Executable path; "" if unavailable |
err |
error or nil |
nil indicates success |
Behavior
A valid routing context must be passed explicitly; otherwise a Lua exception is raised. Returns an error if there is no source IP, the network type is not TCP/UDP, lookup fails, or the platform is unsupported.
pid, name, and path are never nil, but may retain partial information on failure; check err before using them. If there is no source IP or the network type is unsupported, returns 0, "", "", err; otherwise returns the platform lookup results unchanged.
The lookup uses the first source IP and source port. If target IPs are available, it also passes the first target IP and target port. The platform lookup implementation determines the exact matching behavior.
Lookup capabilities depend on the platform and permissions. Windows, Linux, and macOS provide built-in implementations. Android requires the runtime environment to register a lookup implementation, and even successful results may have no name or path. iOS and other unsupported platforms return an error.
Example
local pid, name, path, err = router.FindProcess(ctx)
if err == nil and name == "curl" then
return "direct", "lua-process"
end