20 KiB
xray.geodata
Предоставляет сопоставление доменов и IP по правилам.
local geodata = require("xray.geodata")
Указатель API
| Категория | Член API | Описание |
|---|---|---|
| Функция | geodata.BuildDomainMatcher(...) |
Создание DomainMatcher |
| Функция | geodata.BuildIPMatcher(...) |
Создание IPMatcher |
| Объект | DomainMatcher |
Объект сопоставления доменов |
| Метод | domainMatcherObj:MatchAny(domain) |
Проверка совпадения домена с любым правилом |
| Метод | domainMatcherObj:Match(domain) |
Получение номеров совпавших правил домена |
| Объект | IPMatcher |
Объект сопоставления IP |
| Метод | ipMatcherObj:Match(ip) |
Сопоставление отдельного IP |
| Метод | ipMatcherObj:AnyMatch(ips) |
Проверка наличия совпавшего IP |
| Метод | ipMatcherObj:Matches(ips) |
Проверка совпадения всего списка IP |
| Метод | ipMatcherObj:FilterIPs(ips) |
Разделение совпавших и несовпавших IP |
| Метод | ipMatcherObj:SetReverse(reverse) |
Установка флага инверсии |
| Метод | ipMatcherObj:ToggleReverse() |
Переключение флага инверсии |
Функции
geodata.BuildDomainMatcher
local domainMatcherObj = geodata.BuildDomainMatcher(rule1, rule2, ...)
Создаёт DomainMatcher из правил доменов.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
rule1, rule2, ... |
string |
Обязательны; хотя бы одно правило домена, каждое передаётся отдельно |
Возвращаемые значения
| Значение | Тип | Описание |
|---|---|---|
domainMatcherObj |
DomainMatcher |
Экземпляр сопоставления доменов |
Поведение
Если правила не переданы, тип аргумента неверен или произошла ошибка разбора правил, загрузки ресурсов или создания объекта, возникает исключение Lua.
Поддерживаются domain:, full:, keyword:, regexp:, dotless:, geosite: и ext: (также ext-domain: / ext-site:). Форматы описаны в правилах доменов маршрутизации. Файлы GeoSite загружаются из каталога ресурсов.
Строки без префикса по умолчанию используют правило domain:.
Кроме регулярных выражений, правила при создании приводятся к нижнему регистру.
Пример
local sitesObj = geodata.BuildDomainMatcher(
"example.com", "full:other.example"
)
geodata.BuildIPMatcher
local ipMatcherObj = geodata.BuildIPMatcher(rule1, rule2, ...)
Создаёт IPMatcher из правил IP.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
rule1, rule2, ... |
string |
Обязательны; хотя бы одно правило IP, каждое передаётся отдельно |
Возвращаемые значения
| Значение | Тип | Описание |
|---|---|---|
ipMatcherObj |
IPMatcher |
Экземпляр сопоставления IP |
Поведение
Если правила не переданы, тип аргумента неверен, правило является пустой строкой или произошла ошибка разбора правил, загрузки ресурсов или создания объекта, возникает исключение Lua.
Поддерживаются IP, CIDR, geoip:, ext: (также ext-ip:) и правила инверсии !. Сочетание правил описано в правилах IP маршрутизации. Файлы GeoIP загружаются из каталога ресурсов.
Пример
local privateIPsObj = geodata.BuildIPMatcher(
"10.0.0.0/8", "192.168.0.0/16", "fc00::/7"
)
Объекты
DomainMatcher
| Свойство | Описание |
|---|---|
| Базовый тип Go | Реализация интерфейса geodata.DomainMatcher |
| Представление в Lua | userdata |
| Получение | Возвращаемое значение geodata.BuildDomainMatcher(...) |
Общие соглашения
Методы сопоставления принимают одну строку домена. nil, отсутствие аргумента, неверный тип или число аргументов вызывают исключение Lua.
Входной домен не приводится к нижнему регистру автоматически; при необходимости это должен делать скрипт.
MatchAny
local matched = domainMatcherObj:MatchAny(domain)
Проверяет, совпадает ли домен хотя бы с одним правилом.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
domain |
string |
Обязателен; домен для сопоставления |
Возвращаемые значения
| Значение | Тип | Описание |
|---|---|---|
matched |
boolean |
true при совпадении, иначе false |
Пример
local matched = sitesObj:MatchAny("www.example.com")
Match
local indices = domainMatcherObj:Match(domain)
Получает номера правил, с которыми совпал домен.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
domain |
string |
Обязателен; домен для сопоставления |
Возвращаемые значения
| Значение | Тип | Описание |
|---|---|---|
indices |
[]uint32 или nil |
Номера совпавших правил; при отсутствии совпадений — nil или срез длины 0 |
Поведение
Номера правил начинаются с 0 и соответствуют порядку правил, переданных при создании. Порядок результатов не гарантируется; возможны повторяющиеся номера. Записи, развёрнутые из GeoSite, сохраняют номер исходного правила.
Если те же правила сохранены в массиве Lua, исходное правило можно получить через rules[ruleNumber + 1]. Доступ к срезам описан в разделе Типы данных.
Пример
local indices = sitesObj:Match("www.example.com")
if indices ~= nil then
for i = 1, #indices do
local ruleNumber = indices[i]
end
end
IPMatcher
| Свойство | Описание |
|---|---|
| Базовый тип Go | Реализация интерфейса geodata.IPMatcher |
| Представление в Lua | userdata |
| Получение | Возвращаемое значение geodata.BuildIPMatcher(...) |
Общие соглашения
Для отдельного IP используется net.IP; для сопоставления или фильтрации списков формы ввода описаны в разделе Ввод списка IP. Строки IP-адресов не преобразуются в net.IP автоматически.
Методы сопоставления и фильтрации принимают явно переданный nil. Отсутствие аргументов, неверный тип или число аргументов вызывают исключение Lua.
Match
local matched = ipMatcherObj:Match(ip)
Проверяет, совпадает ли отдельный IP с правилами.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
ip |
net.IP или nil |
Обязателен; нужно передать явно |
Возвращаемые значения
| Значение | Тип | Описание |
|---|---|---|
matched |
boolean |
true, если допустимый IP совпал; false для nil или недопустимого IP |
Поведение
"" или пустая таблица {} трактуются как пустой IP и возвращают false. Строки не разбираются как текст IP-адреса.
AnyMatch
local matched = ipMatcherObj:AnyMatch(ips)
Проверяет, совпадает ли с правилами хотя бы один допустимый IP.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
ips |
Ввод списка IP | Обязателен; нужно передать явно; допускается nil |
Возвращаемые значения
| Значение | Тип | Описание |
|---|---|---|
matched |
boolean |
true, если совпал хотя бы один допустимый IP; false для nil, пустого списка или отсутствия совпадений |
Matches
local matched = ipMatcherObj:Matches(ips)
Проверяет, совпадает ли с правилами весь список IP.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
ips |
Ввод списка IP | Обязателен; нужно передать явно; допускается nil |
Возвращаемые значения
| Значение | Тип | Описание |
|---|---|---|
matched |
boolean |
true, если весь список удовлетворяет условиям; false для nil, пустого списка или списка с недопустимыми IP |
Поведение
Сочетание правил может содержать несколько внутренних объектов сопоставления. Один внутренний объект должен сопоставить весь список.
Например, для geodata.BuildIPMatcher("192.168.1.0/24", "geoip:us") список с 192.168.1.1 и 8.8.8.8 даёт false у Matches: первый IP совпадает с пользовательским CIDR, второй — с geoip:us, но эти правила принадлежат разным внутренним объектам, и ни один не сопоставляет весь список.
Если нужно проверить лишь наличие совпавшего адреса, используйте AnyMatch.
FilterIPs
local matched, unmatched = ipMatcherObj:FilterIPs(ips)
Разделяет допустимые IP на совпавшие и несовпавшие группы.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
ips |
Ввод списка IP | Обязателен; нужно передать явно; допускается nil |
Возвращаемые значения
| Значение | Тип | Описание |
|---|---|---|
matched |
[]net.IP |
Совпавшие IP; никогда не nil |
unmatched |
[]net.IP |
Несовпавшие IP; никогда не nil |
Поведение
Группа без результатов является пустым срезом. При передаче nil, пустого списка или только недопустимых IP обе группы — пустые срезы.
Недопустимые IP отбрасываются; порядок результатов не обязательно совпадает с порядком ввода.
SetReverse
ipMatcherObj:SetReverse(reverse)
Устанавливает флаг инверсии каждого внутреннего объекта сопоставления.
Параметры
| Параметр | Тип | Описание / Требования |
|---|---|---|
reverse |
boolean |
Обязателен; true включает инверсию, false отключает |
Возвращаемые значения
Нет возвращаемых значений.
Поведение
nil, отсутствие аргумента или неверный тип вызывают исключение Lua. Операция заменяет прежний флаг инверсии каждого внутреннего объекта, включая флаги ! из правил. Инверсия действует только на семейства адресов исходного правила и не сопоставляет недопустимые IP.
Установленное состояние инверсии сохраняется в текущем объекте сопоставления. Если последующие вызовы Hook повторно используют этот объект, изменённое состояние продолжает действовать. См. Состояние в экземплярах пула.
Пример
После инверсии 10.0.0.0/8 сопоставляются допустимые адреса IPv4 вне этого диапазона:
local ipMatcherObj = geodata.BuildIPMatcher("10.0.0.0/8")
ipMatcherObj:SetReverse(true)
ToggleReverse
ipMatcherObj:ToggleReverse()
Переключает флаг инверсии каждого внутреннего объекта сопоставления.
Параметры
Дополнительных параметров нет.
Возвращаемые значения
Нет возвращаемых значений.
Поведение
Каждый внутренний объект в сочетании правил переключает собственный флаг инверсии. Результат не равнозначен логическому отрицанию всего сочетания. Новое состояние инверсии сохраняется в текущем объекте сопоставления. Если последующие вызовы Hook повторно используют этот объект, изменённое состояние продолжает действовать. См. Состояние в экземплярах пула.