XTLS_Xray-docs-next/docs/ru/development/lua/reference/hook-routing.md

Hook маршрутизации

При выборе исходящего подключения ядро вызывает глобальную функцию HandleRoute из routing.script. Настройка и полные примеры приведены в руководстве по скриптам маршрутизации.

Указатель API

Категория	Член API	Описание
Hook	HandleRoute(...)	Выбор исходящего подключения для запроса
Объект	routing.Context	Контекст маршрутизации текущего запроса
Метод	ctx:GetSourceIPs()	Получение IP источника
Метод	ctx:GetTargetIPs()	Получение IP назначения
Метод	ctx:GetLocalIPs()	Получение локальных IP
Метод	ctx:GetAttributes()	Получение атрибутов запроса

Интерфейс Hook

HandleRoute(...)

function HandleRoute(ctx, inboundTag, sourcePort, targetPort,
    localPort, targetDomain, network, protocol, user,
    vlessRoute, skipDNSResolve)
    return outboundTag, ruleTag, err
end

Выбирает исходящее подключение для текущего запроса и при необходимости возвращает имя правила или ошибку.

Параметры

Ядро всегда передаёт все 11 параметров в указанном порядке; ни один из них не равен nil. В определении функции можно опустить неиспользуемые параметры в конце — это не меняет значения, передаваемые ядром.

Параметр	Тип	Описание	Пустые значения и значения по умолчанию
ctx	routing.Context	Контекст текущего запроса	Всегда допустимый userdata
inboundTag	string	Тег входящего подключения	"", если тег не задан или нет входящей информации
sourcePort	number	Порт источника, 0 .. 65535	0, если нет допустимого адреса источника
targetPort	number	Порт назначения, 0 .. 65535	0, если нет допустимого адреса назначения
localPort	number	Локальный порт входящего соединения, 0 .. 65535	0, если нет допустимого локального адреса
targetDomain	string	Действующий домен, обнаруженный анализом трафика, имеет приоритет; иначе используется домен цели соединения. Значение приводится к нижнему регистру	"", если цель — IP без действующего обнаруженного домена или нет информации о цели
network	number	Тип сети; сравнивается с константами вроде router.NetworkTCP	NetworkUnknown (0), если нет исходящей информации или тип сети неизвестен
protocol	string	Протокол, обнаруженный анализом трафика	"", если нет информации об обнаруженном протоколе
user	string	Email пользователя	"", если нет входящей информации, данных пользователя или email не задан
vlessRoute	number	Значение маршрута из 7-го и 8-го байтов UUID VLESS, 0 .. 65535	0 при отсутствии информации; само значение также может быть 0
skipDNSResolve	boolean	При true нужно пропустить DNS-запросы, чтобы избежать петель	false, если нет этого флага или дополнительных данных запроса

Возвращаемые значения

Значение	Тип	Описание
outboundTag	string или nil	Тег исходящего подключения; nil или "" означает, что оно не выбрано
ruleTag	string или nil	Необязательное имя правила; nil, отсутствие значения или "" означает отсутствие имени
err	error, string или nil	Только nil означает отсутствие ошибки

Поведение

Ядро последовательно проверяет err, outboundTag и ruleTag, останавливаясь при первой ошибке. Если err не равен nil, первые два значения игнорируются. Если исходящее подключение не выбрано, ruleTag игнорируется.

При успехе значения ruleTag и err в конце можно опустить, например return "direct". Ошибка должна быть в третьей позиции, например return nil, nil, "ошибка маршрутизации"; return nil, "ошибка маршрутизации" не сообщает об ошибке.

Результат скрипта	Действие ядра
Проверка успешна, outboundTag непустой	Использует соответствующее исходящее подключение; если тег не существует, закрывает соединение
Исходящее подключение не выбрано	Использует исходящее подключение по умолчанию
Возвращена ошибка, неверный тип значения или исключение выполнения	Записывает ошибку в журнал и пробует исходящее подключение по умолчанию

Исходящее подключение по умолчанию — первое в конфигурации; если оно недоступно, соединение закрывается. Для блокировки трафика явно возвращайте тег настроенного исходящего подключения blackhole, а не используйте это поведение с несуществующим тегом.

Связанные объекты

routing.Context

routing.Context представляет контекст маршрутизации текущего запроса и доступен в HandleRoute через параметр ctx.

Свойство	Описание
Базовый тип Go	Интерфейс routing.Context из features/routing
Представление в Lua	userdata
Получение	Первый параметр HandleRoute, передаваемый ядром

Все методы ниже не принимают дополнительных параметров. Операции с IP и срезами описаны в разделе Типы данных.

GetSourceIPs

local ips = ctx:GetSourceIPs()

Получает IP-адреса источника запроса.

Параметры

Дополнительных параметров нет.

Возвращаемые значения

Значение	Тип	Описание
ips	[]net.IP или nil	Список IP соответствующего адреса

Поведение

Возвращает nil, если нет входящего подключения, адрес источника недопустим или не является IP-адресом.

GetTargetIPs

local ips = ctx:GetTargetIPs()

Получает IP-адреса назначения запроса.

Параметры

Дополнительных параметров нет.

Возвращаемые значения

Значение	Тип	Описание
ips	[]net.IP или nil	Список IP соответствующего адреса

Поведение

Возвращает nil, если нет исходящего подключения, адрес назначения недопустим или является доменным именем.

GetLocalIPs

local ips = ctx:GetLocalIPs()

Получает локальные IP-адреса входящего соединения.

Параметры

Дополнительных параметров нет.

Возвращаемые значения

Значение	Тип	Описание
ips	[]net.IP или nil	Список IP соответствующего адреса

Поведение

Возвращает nil, если нет входящего подключения, локальный адрес недопустим или не является IP-адресом.

GetAttributes

local attributes = ctx:GetAttributes()

Получает атрибуты текущего запроса.

Параметры

Дополнительных параметров нет.

Возвращаемые значения

Значение	Тип	Описание
attributes	map[string]string	Всегда userdata; никогда не nil

Поведение

Читайте атрибуты через attributes[key], где key должен быть строкой. Существующий ключ возвращает строку (возможно ""), отсутствующий — nil.

Значение и использование атрибутов описаны в поле attrs конфигурации маршрутизации.

Пример

local attributes = ctx:GetAttributes()
if attributes[":method"] == "GET" then
    return "direct", "lua-get"
end