# 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
```