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