Xray-core: Add Lua script for dns and routing

https://github.com/XTLS/Xray-core/pull/6823
2026-10-13 09:48:13 +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,119 @@
+# xray.router
+
+Предоставляет константы и вспомогательные интерфейсы для [скриптов маршрутизации](../guide/routing.md). Параметры запроса и контекст описаны в [Hook маршрутизации](./hook-routing.md).
+
+```lua
+local router = require("xray.router")
+```
+
+## Указатель API
+
+| Категория | Член API                                                   | Описание                                         |
+| --------- | ---------------------------------------------------------- | ------------------------------------------------ |
+| Константа | [`router.NetworkUnknown`](#константы)                      | Неизвестная сеть                                 |
+| Константа | [`router.NetworkTCP`](#константы)                          | TCP                                              |
+| Константа | [`router.NetworkUDP`](#константы)                          | UDP                                              |
+| Константа | [`router.NetworkUNIX`](#константы)                         | UNIX                                             |
+| Константа | [`router.LocalOS`](#константы)                             | Платформа выполнения                             |
+| Функция   | [`router:PickOutbound(balancerTag)`](#router-pickoutbound) | Выбор исходящего подключения через балансировщик |
+| Функция   | [`router.FindProcess(ctx)`](#router-findprocess)           | Поиск процесса локального соединения             |
+
+## Константы
+
+| Имя                     | Тип      | Значение / Описание                                                          |
+| ----------------------- | -------- | ---------------------------------------------------------------------------- |
+| `router.NetworkUnknown` | `number` | `0`, неизвестная сеть                                                        |
+| `router.NetworkTCP`     | `number` | `2`, TCP                                                                     |
+| `router.NetworkUDP`     | `number` | `3`, UDP                                                                     |
+| `router.NetworkUNIX`    | `number` | `4`, UNIX                                                                    |
+| `router.LocalOS`        | `string` | Текущая платформа выполнения, например `"windows"`, `"linux"` или `"darwin"` |
+
+Параметр `network` из [Hook маршрутизации](./hook-routing.md#handleroute) можно сравнивать с сетевыми константами:
+
+```lua
+if network == router.NetworkUDP then
+    return "direct", "lua-udp"
+end
+```
+
+## Функции
+
+### router:PickOutbound
+
+```lua
+local outboundTag, err = router:PickOutbound(balancerTag)
+```
+
+Выбирает исходящее подключение через указанный балансировщик.
+
+**Параметры**
+
+| Параметр      | Тип      | Описание / Требования                                                                                                  |
+| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `balancerTag` | `string` | Значение `tag` нужного балансировщика, настроенного в [`routing.balancers`](../../../config/routing.md#balancerobject) |
+
+**Возвращаемые значения**
+
+| Значение      | Тип                                        | Описание                                                      |
+| ------------- | ------------------------------------------ | ------------------------------------------------------------- |
+| `outboundTag` | `string` или `nil`                         | При успехе — непустой `tag` выбранного исходящего подключения |
+| `err`         | [`error`](./data-types.md#error) или `nil` | `nil` означает успех                                          |
+
+**Поведение**
+
+Нужно явно передать строку, иначе возникает исключение Lua. Пустая строка `""` выполняет поиск по пустому `tag`.
+
+Перед использованием результата проверьте `err`. Если балансировщик не существует, возвращается `nil, err`; если существует, но не выбрал исходящее подключение, — `"", err`. Когда срабатывает настроенный `fallbackTag`, возвращаются этот тег исходящего подключения и `nil`.
+
+**Пример**
+
+Ниже используется балансировщик с `tag` `"proxy-pool"`, а результат передаётся согласно [соглашению о возвращаемых значениях Hook маршрутизации](./hook-routing.md#возвращаемые-значения):
+
+```lua
+local outboundTag, err = router:PickOutbound("proxy-pool")
+return outboundTag, "lua-balance", err
+```
+
+Полный пример приведён в [руководстве по скриптам маршрутизации](../guide/routing.md#связь-с-конфигурациеи-маршрутизации).
+
+### router.FindProcess
+
+```lua
+local pid, name, path, err = router.FindProcess(ctx)
+```
+
+Находит процесс на локальной машине, связанный с текущим соединением.
+
+**Параметры**
+
+| Параметр | Тип                                                    | Описание / Требования                                    |
+| -------- | ------------------------------------------------------ | -------------------------------------------------------- |
+| `ctx`    | [`routing.Context`](./hook-routing.md#routing-context) | Контекст текущего запроса, переданный Hook маршрутизации |
+
+**Возвращаемые значения**
+
+| Значение | Тип                                        | Описание                                         |
+| -------- | ------------------------------------------ | ------------------------------------------------ |
+| `pid`    | `number`                                   | ID процесса; обычно `0`, если не получен         |
+| `name`   | `string`                                   | Имя процесса; `""`, если не получено             |
+| `path`   | `string`                                   | Путь к исполняемому файлу; `""`, если не получен |
+| `err`    | [`error`](./data-types.md#error) или `nil` | `nil` означает успех                             |
+
+**Поведение**
+
+Нужно явно передать допустимый контекст маршрутизации, иначе возникает исключение Lua. Если нет IP источника, тип сети не TCP/UDP, поиск не удался или платформа не поддерживается, возвращается ошибка.
+
+`pid`, `name` и `path` никогда не равны `nil`, но при ошибке могут содержать частичные данные; перед использованием проверьте `err`. Если нет IP источника или тип сети не поддерживается, возвращается `0, "", "", err`; в остальных случаях результат платформенного поиска возвращается без изменений.
+
+Поиск использует первый IP источника и порт источника. Если есть IP назначения, также передаются первый IP назначения и порт назначения. Точный способ сопоставления определяет платформенная реализация поиска.
+
+Возможности поиска зависят от платформы и прав доступа. Windows, Linux и macOS имеют встроенные реализации. В Android среда выполнения должна зарегистрировать реализацию поиска; даже при успехе имя или путь могут отсутствовать. iOS и другие неподдерживаемые платформы возвращают ошибку.
+
+**Пример**
+
+```lua
+local pid, name, path, err = router.FindProcess(ctx)
+if err == nil and name == "curl" then
+    return "direct", "lua-process"
+end
+```