Xray-core: Add Lua script for dns and routing

https://github.com/XTLS/Xray-core/pull/6823
2026-10-12 09:18:19 +03:00 · 2026-10-11 09:55:19 +08:00
parent 4c8f3b2b7e
commit f179efd35d
48 changed files with 4950 additions and 0 deletions
@@ -0,0 +1,67 @@
+# Hook DNS
+
+Во время запросов встроенного DNS ядро вызывает глобальную функцию `HandleDNSQuery` из `dns.script`. Настройка и полные примеры приведены в [руководстве по скриптам DNS](../guide/dns.md).
+
+## Указатель API
+
+| Категория | Член API                                 | Описание               |
+| --------- | ---------------------------------------- | ---------------------- |
+| Hook      | [`HandleDNSQuery(...)`](#handlednsquery) | Обработка DNS-запросов |
+
+## Интерфейс Hook
+
+### HandleDNSQuery(...)
+
+```lua
+function HandleDNSQuery(domain, ipv4, ipv6, fake)
+    return ips, ttl, err
+end
+```
+
+Обрабатывает один DNS-запрос и возвращает срез IP, TTL или ошибку.
+
+#### Параметры
+
+Ядро всегда передаёт все четыре параметра; ни один из них не равен `nil`.
+
+| Параметр | Тип       | Описание                                         |
+| -------- | --------- | ------------------------------------------------ |
+| `domain` | `string`  | Запрашиваемый домен; непустой, в нижнем регистре |
+| `ipv4`   | `boolean` | Разрешены ли запросы адресов IPv4                |
+| `ipv6`   | `boolean` | Разрешены ли запросы адресов IPv6                |
+| `fake`   | `boolean` | Разрешён ли FakeDNS для этого запроса            |
+
+`ipv4` и `ipv6` уже ограничены глобальным [`queryStrategy`](../../../config/dns.md#dnsobject); хотя бы один равен `true`. Обычно при запросах к вышестоящему серверу эти три булевых параметра передаются без изменений.
+
+#### Возвращаемые значения
+
+| Значение | Тип                                                  | Описание                                                                                |
+| -------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `ips`    | [`[]net.IP`](./data-types.md#net-ip-1) или `nil`     | Результаты запроса; нужен срез, массив Lua не принимается                               |
+| `ttl`    | `number` или `nil`                                   | TTL в секундах; при `err == nil` должен быть целым числом в диапазоне `0 .. 4294967295` |
+| `err`    | [`error`](./data-types.md#error), `string` или `nil` | Только `nil` означает отсутствие ошибки                                                 |
+
+#### Поведение
+
+Ядро последовательно проверяет `err`, `ttl` и `ips`, останавливаясь при первой ошибке. Если `err` не равен `nil`, два остальных значения игнорируются. При отсутствии ошибки нужно указать допустимый TTL, даже если результат IP пуст.
+
+Для пустого ответа используйте `return nil, 0, nil`. Ошибка должна быть в третьей позиции, например `return nil, nil, "ошибка запроса"`.
+
+| Результат скрипта                                                  | Действие ядра                                |
+| ------------------------------------------------------------------ | -------------------------------------------- |
+| Проверка успешна, `ips` непустой                                   | Запрос успешен                               |
+| `err == nil`, TTL допустим, но `ips` равен `nil` или пустому срезу | Запрос завершается неудачей с пустым ответом |
+| Возвращена ошибка, неверный тип значения или исключение выполнения | Запрос завершается неудачей                  |
+
+#### Пример
+
+Можно напрямую передать все три возвращаемых значения [`serverObj:Query`](./module-dns.md#query):
+
+```lua
+local dns = require("xray.dns")
+local serverObj = dns.Servers[1]
+
+function HandleDNSQuery(domain, ipv4, ipv6, fake)
+    return serverObj:Query(domain, ipv4, ipv6, fake)
+end
+```