14 KiB
xray.geodata
Provides rule-based matching for domains and IPs.
local geodata = require("xray.geodata")
API Index
| Category | Member | Description |
|---|---|---|
| Function | geodata.BuildDomainMatcher(...) |
Create a DomainMatcher |
| Function | geodata.BuildIPMatcher(...) |
Create an IPMatcher |
| Object | DomainMatcher |
Domain matcher |
| Method | domainMatcherObj:MatchAny(domain) |
Check whether a domain matches any rule |
| Method | domainMatcherObj:Match(domain) |
Get the indices of matching domain rules |
| Object | IPMatcher |
IP matcher |
| Method | ipMatcherObj:Match(ip) |
Match a single IP |
| Method | ipMatcherObj:AnyMatch(ips) |
Check whether any IP matches |
| Method | ipMatcherObj:Matches(ips) |
Check whether the entire IP list matches |
| Method | ipMatcherObj:FilterIPs(ips) |
Separate matching and non-matching IPs |
| Method | ipMatcherObj:SetReverse(reverse) |
Set the reverse flag |
| Method | ipMatcherObj:ToggleReverse() |
Toggle the reverse flag |
Functions
geodata.BuildDomainMatcher
local domainMatcherObj = geodata.BuildDomainMatcher(rule1, rule2, ...)
Creates a DomainMatcher from domain rules.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
rule1, rule2, ... |
string |
Required; at least one domain rule, passed individually |
Return Values
| Return value | Type | Description |
|---|---|---|
domainMatcherObj |
DomainMatcher |
A domain matcher instance |
Behavior
Raises a Lua exception if no rules are supplied, an argument has the wrong type, or rule parsing, resource loading, or construction fails.
Supports domain:, full:, keyword:, regexp:, dotless:, geosite:, and ext: (also written as ext-domain: / ext-site:). See routing domain rules for the formats. GeoSite files are loaded from the resource directory.
Strings without a prefix use domain: rules by default.
Except for regular expressions, rules are converted to lowercase during construction.
Example
local sitesObj = geodata.BuildDomainMatcher(
"example.com", "full:other.example"
)
geodata.BuildIPMatcher
local ipMatcherObj = geodata.BuildIPMatcher(rule1, rule2, ...)
Creates an IPMatcher from IP rules.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
rule1, rule2, ... |
string |
Required; at least one IP rule, passed individually |
Return Values
| Return value | Type | Description |
|---|---|---|
ipMatcherObj |
IPMatcher |
An IP matcher instance |
Behavior
Raises a Lua exception if no rules are supplied, an argument has the wrong type, a rule is an empty string, or rule parsing, resource loading, or construction fails.
Supports IPs, CIDR, geoip:, ext: (also written as ext-ip:), and ! reverse rules. See routing IP rules for how rules are combined. GeoIP files are loaded from the resource directory.
Example
local privateIPsObj = geodata.BuildIPMatcher(
"10.0.0.0/8", "192.168.0.0/16", "fc00::/7"
)
Objects
DomainMatcher
| Property | Description |
|---|---|
| Underlying Go type | An implementation of the geodata.DomainMatcher interface |
| Lua representation | userdata |
| Obtained from | The return value of geodata.BuildDomainMatcher(...) |
Common Conventions
Matching methods take one domain string. nil, omitted arguments, incorrect types, or an incorrect argument count raise a Lua exception.
The input domain is not automatically converted to lowercase; the script must do this as needed.
MatchAny
local matched = domainMatcherObj:MatchAny(domain)
Checks whether a domain matches at least one rule.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
domain |
string |
Required; domain to match |
Return Values
| Return value | Type | Description |
|---|---|---|
matched |
boolean |
true if matched, otherwise false |
Example
local matched = sitesObj:MatchAny("www.example.com")
Match
local indices = domainMatcherObj:Match(domain)
Gets the indices of rules matched by the domain.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
domain |
string |
Required; domain to match |
Return Values
| Return value | Type | Description |
|---|---|---|
indices |
[]uint32 or nil |
Matching rule indices; nil or a slice of length 0 if nothing matches |
Behavior
Rule indices start at 0 and correspond to the order of rules supplied during construction. Result order is not guaranteed, and duplicate indices may occur. Entries expanded from GeoSite retain the index of their parent rule.
If you store the same rules in a Lua array, use rules[ruleNumber + 1] to get the original rule. See Data Types for slice access.
Example
local indices = sitesObj:Match("www.example.com")
if indices ~= nil then
for i = 1, #indices do
local ruleNumber = indices[i]
end
end
IPMatcher
| Property | Description |
|---|---|
| Underlying Go type | An implementation of the geodata.IPMatcher interface |
| Lua representation | userdata |
| Obtained from | The return value of geodata.BuildIPMatcher(...) |
Common Conventions
For a single IP, use net.IP. For matching or filtering lists, see IP List Input. IP address strings are not automatically parsed into net.IP.
Matching and filtering methods all accept explicit nil. Omitted arguments, incorrect types, or an incorrect argument count raise a Lua exception.
Match
local matched = ipMatcherObj:Match(ip)
Checks whether a single IP matches the rules.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
ip |
net.IP or nil |
Required; must be passed explicitly |
Return Values
| Return value | Type | Description |
|---|---|---|
matched |
boolean |
true if a valid IP matches; false for nil or an invalid IP |
Behavior
Passing "" or an empty table {} is treated as an empty IP and returns false. Strings are not parsed as IP address text.
AnyMatch
local matched = ipMatcherObj:AnyMatch(ips)
Checks whether at least one valid IP matches the rules.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
ips |
IP List Input | Required; must be passed explicitly; nil is allowed |
Return Values
| Return value | Type | Description |
|---|---|---|
matched |
boolean |
true if at least one valid IP matches; false for nil, an empty list, or no match |
Matches
local matched = ipMatcherObj:Matches(ips)
Checks whether the entire IP list matches the rules.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
ips |
IP List Input | Required; must be passed explicitly; nil is allowed |
Return Values
| Return value | Type | Description |
|---|---|---|
matched |
boolean |
true if the entire list meets the matching requirements; false for nil, an empty list, or a list containing invalid IPs |
Behavior
Combined rules may contain multiple internal matchers. A single internal matcher must match the entire list.
For example, with geodata.BuildIPMatcher("192.168.1.0/24", "geoip:us"), a list containing both 192.168.1.1 and 8.8.8.8 makes Matches return false: the first IP matches the custom CIDR, and the second matches geoip:us, but these belong to different internal matchers, and neither matches the entire list.
If you only need to check whether any address matches, use AnyMatch.
FilterIPs
local matched, unmatched = ipMatcherObj:FilterIPs(ips)
Separates valid IPs into matching and non-matching groups.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
ips |
IP List Input | Required; must be passed explicitly; nil is allowed |
Return Values
| Return value | Type | Description |
|---|---|---|
matched |
[]net.IP |
Matching IPs; never nil |
unmatched |
[]net.IP |
Non-matching IPs; never nil |
Behavior
A group with no results is an empty slice. For nil, an empty list, or a list containing only invalid IPs, both groups are empty slices.
Invalid IPs are discarded, and result order is not guaranteed to match the input order.
SetReverse
ipMatcherObj:SetReverse(reverse)
Sets the reverse flag on each internal matcher.
Parameters
| Parameter | Type | Description / Requirements |
|---|---|---|
reverse |
boolean |
Required; true enables reverse matching, false disables it |
Return Values
No return values.
Behavior
nil, omission, or an incorrect type raises a Lua exception. This operation overrides each internal matcher's existing reverse flag, including flags specified with ! in rules. Reverse matching applies only to address families present in the original rules and does not match invalid IPs.
The resulting reverse state is stored in the current matcher object. If later Hook calls reuse that object, the modified state remains in effect. See State in Pooled Instances.
Example
Reversing 10.0.0.0/8 matches valid IPv4 addresses outside that range:
local ipMatcherObj = geodata.BuildIPMatcher("10.0.0.0/8")
ipMatcherObj:SetReverse(true)
ToggleReverse
ipMatcherObj:ToggleReverse()
Toggles the reverse flag on each internal matcher.
Parameters
No additional parameters.
Return Values
No return values.
Behavior
Each internal matcher in combined rules toggles its own reverse flag. This is not equivalent to logically negating the combined result. The resulting reverse state is stored in the current matcher object. If later Hook calls reuse that object, the modified state remains in effect. See State in Pooled Instances.