# xray.geodata

Предоставляет сопоставление доменов и IP по правилам.

```lua
local geodata = require("xray.geodata")
```

## Указатель API

| Категория | Член API                                                         | Описание                                    |
| --------- | ---------------------------------------------------------------- | ------------------------------------------- |
| Функция   | [`geodata.BuildDomainMatcher(...)`](#geodata-builddomainmatcher) | Создание `DomainMatcher`                    |
| Функция   | [`geodata.BuildIPMatcher(...)`](#geodata-buildipmatcher)         | Создание `IPMatcher`                        |
| Объект    | [`DomainMatcher`](#domainmatcher)                                | Объект сопоставления доменов                |
| Метод     | [`domainMatcherObj:MatchAny(domain)`](#matchany)                 | Проверка совпадения домена с любым правилом |
| Метод     | [`domainMatcherObj:Match(domain)`](#match)                       | Получение номеров совпавших правил домена   |
| Объект    | [`IPMatcher`](#ipmatcher)                                        | Объект сопоставления IP                     |
| Метод     | [`ipMatcherObj:Match(ip)`](#match-1)                             | Сопоставление отдельного IP                 |
| Метод     | [`ipMatcherObj:AnyMatch(ips)`](#anymatch)                        | Проверка наличия совпавшего IP              |
| Метод     | [`ipMatcherObj:Matches(ips)`](#matches)                          | Проверка совпадения всего списка IP         |
| Метод     | [`ipMatcherObj:FilterIPs(ips)`](#filterips)                      | Разделение совпавших и несовпавших IP       |
| Метод     | [`ipMatcherObj:SetReverse(reverse)`](#setreverse)                | Установка флага инверсии                    |
| Метод     | [`ipMatcherObj:ToggleReverse()`](#togglereverse)                 | Переключение флага инверсии                 |

## Функции

### geodata.BuildDomainMatcher

```lua
local domainMatcherObj = geodata.BuildDomainMatcher(rule1, rule2, ...)
```

Создаёт [`DomainMatcher`](#domainmatcher) из правил доменов.

**Параметры**

| Параметр            | Тип      | Описание / Требования                                                |
| ------------------- | -------- | -------------------------------------------------------------------- |
| `rule1, rule2, ...` | `string` | Обязательны; хотя бы одно правило домена, каждое передаётся отдельно |

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

| Значение           | Тип                               | Описание                        |
| ------------------ | --------------------------------- | ------------------------------- |
| `domainMatcherObj` | [`DomainMatcher`](#domainmatcher) | Экземпляр сопоставления доменов |

**Поведение**

Если правила не переданы, тип аргумента неверен или произошла ошибка разбора правил, загрузки ресурсов или создания объекта, возникает исключение Lua.

Поддерживаются `domain:`, `full:`, `keyword:`, `regexp:`, `dotless:`, `geosite:` и `ext:` (также `ext-domain:` / `ext-site:`). Форматы описаны в [правилах доменов маршрутизации](../../../config/routing.md#ruleobject). Файлы GeoSite загружаются из [каталога ресурсов](../../../config/env.md#путь-к-фаилам-ресурсов).

Строки без префикса по умолчанию используют правило `domain:`.

Кроме регулярных выражений, правила при создании приводятся к нижнему регистру.

**Пример**

```lua
local sitesObj = geodata.BuildDomainMatcher(
    "example.com", "full:other.example"
)
```

### geodata.BuildIPMatcher

```lua
local ipMatcherObj = geodata.BuildIPMatcher(rule1, rule2, ...)
```

Создаёт [`IPMatcher`](#ipmatcher) из правил IP.

**Параметры**

| Параметр            | Тип      | Описание / Требования                                            |
| ------------------- | -------- | ---------------------------------------------------------------- |
| `rule1, rule2, ...` | `string` | Обязательны; хотя бы одно правило IP, каждое передаётся отдельно |

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

| Значение       | Тип                       | Описание                   |
| -------------- | ------------------------- | -------------------------- |
| `ipMatcherObj` | [`IPMatcher`](#ipmatcher) | Экземпляр сопоставления IP |

**Поведение**

Если правила не переданы, тип аргумента неверен, правило является пустой строкой или произошла ошибка разбора правил, загрузки ресурсов или создания объекта, возникает исключение Lua.

Поддерживаются IP, CIDR, `geoip:`, `ext:` (также `ext-ip:`) и правила инверсии `!`. Сочетание правил описано в [правилах IP маршрутизации](../../../config/routing.md#ruleobject). Файлы GeoIP загружаются из [каталога ресурсов](../../../config/env.md#путь-к-фаилам-ресурсов).

**Пример**

```lua
local privateIPsObj = geodata.BuildIPMatcher(
    "10.0.0.0/8", "192.168.0.0/16", "fc00::/7"
)
```

## Объекты

### DomainMatcher

| Свойство            | Описание                                                                               |
| ------------------- | -------------------------------------------------------------------------------------- |
| Базовый тип Go      | Реализация интерфейса `geodata.DomainMatcher`                                          |
| Представление в Lua | `userdata`                                                                             |
| Получение           | Возвращаемое значение [`geodata.BuildDomainMatcher(...)`](#geodata-builddomainmatcher) |

**Общие соглашения**

Методы сопоставления принимают одну строку домена. `nil`, отсутствие аргумента, неверный тип или число аргументов вызывают исключение Lua.

Входной домен не приводится к нижнему регистру автоматически; при необходимости это должен делать скрипт.

#### MatchAny

```lua
local matched = domainMatcherObj:MatchAny(domain)
```

Проверяет, совпадает ли домен хотя бы с одним правилом.

**Параметры**

| Параметр | Тип      | Описание / Требования               |
| -------- | -------- | ----------------------------------- |
| `domain` | `string` | Обязателен; домен для сопоставления |

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

| Значение  | Тип       | Описание                             |
| --------- | --------- | ------------------------------------ |
| `matched` | `boolean` | `true` при совпадении, иначе `false` |

**Пример**

```lua
local matched = sitesObj:MatchAny("www.example.com")
```

#### Match

```lua
local indices = domainMatcherObj:Match(domain)
```

Получает номера правил, с которыми совпал домен.

**Параметры**

| Параметр | Тип      | Описание / Требования               |
| -------- | -------- | ----------------------------------- |
| `domain` | `string` | Обязателен; домен для сопоставления |

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

| Значение  | Тип                                            | Описание                                                                    |
| --------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
| `indices` | [`[]uint32`](./data-types.md#uint32) или `nil` | Номера совпавших правил; при отсутствии совпадений — `nil` или срез длины 0 |

**Поведение**

Номера правил начинаются с **0** и соответствуют порядку правил, переданных при создании. Порядок результатов не гарантируется; возможны повторяющиеся номера. Записи, развёрнутые из GeoSite, сохраняют номер исходного правила.

Если те же правила сохранены в массиве Lua, исходное правило можно получить через `rules[ruleNumber + 1]`. Доступ к срезам описан в разделе [Типы данных](./data-types.md#slice).

**Пример**

```lua
local indices = sitesObj:Match("www.example.com")
if indices ~= nil then
    for i = 1, #indices do
        local ruleNumber = indices[i]
    end
end
```

### IPMatcher

| Свойство            | Описание                                                                       |
| ------------------- | ------------------------------------------------------------------------------ |
| Базовый тип Go      | Реализация интерфейса `geodata.IPMatcher`                                      |
| Представление в Lua | `userdata`                                                                     |
| Получение           | Возвращаемое значение [`geodata.BuildIPMatcher(...)`](#geodata-buildipmatcher) |

**Общие соглашения**

Для отдельного IP используется [`net.IP`](./data-types.md#net-ip); для сопоставления или фильтрации списков формы ввода описаны в разделе [Ввод списка IP](./data-types.md#ввод-списка-ip). Строки IP-адресов не преобразуются в `net.IP` автоматически.

Методы сопоставления и фильтрации принимают явно переданный `nil`. Отсутствие аргументов, неверный тип или число аргументов вызывают исключение Lua.

#### Match

```lua
local matched = ipMatcherObj:Match(ip)
```

Проверяет, совпадает ли отдельный IP с правилами.

**Параметры**

| Параметр | Тип                                          | Описание / Требования           |
| -------- | -------------------------------------------- | ------------------------------- |
| `ip`     | [`net.IP`](./data-types.md#net-ip) или `nil` | Обязателен; нужно передать явно |

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

| Значение  | Тип       | Описание                                                                  |
| --------- | --------- | ------------------------------------------------------------------------- |
| `matched` | `boolean` | `true`, если допустимый IP совпал; `false` для `nil` или недопустимого IP |

**Поведение**

`""` или пустая таблица `{}` трактуются как пустой IP и возвращают `false`. Строки не разбираются как текст IP-адреса.

#### AnyMatch

```lua
local matched = ipMatcherObj:AnyMatch(ips)
```

Проверяет, совпадает ли с правилами хотя бы один допустимый IP.

**Параметры**

| Параметр | Тип                                              | Описание / Требования                              |
| -------- | ------------------------------------------------ | -------------------------------------------------- |
| `ips`    | [Ввод списка IP](./data-types.md#ввод-списка-ip) | Обязателен; нужно передать явно; допускается `nil` |

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

| Значение  | Тип       | Описание                                                                                                    |
| --------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `matched` | `boolean` | `true`, если совпал хотя бы один допустимый IP; `false` для `nil`, пустого списка или отсутствия совпадений |

#### Matches

```lua
local matched = ipMatcherObj:Matches(ips)
```

Проверяет, совпадает ли с правилами весь список IP.

**Параметры**

| Параметр | Тип                                              | Описание / Требования                              |
| -------- | ------------------------------------------------ | -------------------------------------------------- |
| `ips`    | [Ввод списка IP](./data-types.md#ввод-списка-ip) | Обязателен; нужно передать явно; допускается `nil` |

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

| Значение  | Тип       | Описание                                                                                                         |
| --------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `matched` | `boolean` | `true`, если весь список удовлетворяет условиям; `false` для `nil`, пустого списка или списка с недопустимыми IP |

**Поведение**

Сочетание правил может содержать несколько внутренних объектов сопоставления. Один внутренний объект должен сопоставить весь список.

Например, для `geodata.BuildIPMatcher("192.168.1.0/24", "geoip:us")` список с `192.168.1.1` и `8.8.8.8` даёт `false` у `Matches`: первый IP совпадает с пользовательским CIDR, второй — с `geoip:us`, но эти правила принадлежат разным внутренним объектам, и ни один не сопоставляет весь список.

Если нужно проверить лишь наличие совпавшего адреса, используйте [`AnyMatch`](#anymatch).

#### FilterIPs

```lua
local matched, unmatched = ipMatcherObj:FilterIPs(ips)
```

Разделяет допустимые IP на совпавшие и несовпавшие группы.

**Параметры**

| Параметр | Тип                                              | Описание / Требования                              |
| -------- | ------------------------------------------------ | -------------------------------------------------- |
| `ips`    | [Ввод списка IP](./data-types.md#ввод-списка-ip) | Обязателен; нужно передать явно; допускается `nil` |

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

| Значение    | Тип                                    | Описание                         |
| ----------- | -------------------------------------- | -------------------------------- |
| `matched`   | [`[]net.IP`](./data-types.md#net-ip-1) | Совпавшие IP; никогда не `nil`   |
| `unmatched` | [`[]net.IP`](./data-types.md#net-ip-1) | Несовпавшие IP; никогда не `nil` |

**Поведение**

Группа без результатов является пустым срезом. При передаче `nil`, пустого списка или только недопустимых IP обе группы — пустые срезы.

Недопустимые IP отбрасываются; порядок результатов не обязательно совпадает с порядком ввода.

#### SetReverse

```lua
ipMatcherObj:SetReverse(reverse)
```

Устанавливает флаг инверсии каждого внутреннего объекта сопоставления.

**Параметры**

| Параметр  | Тип       | Описание / Требования                                   |
| --------- | --------- | ------------------------------------------------------- |
| `reverse` | `boolean` | Обязателен; `true` включает инверсию, `false` отключает |

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

Нет возвращаемых значений.

**Поведение**

`nil`, отсутствие аргумента или неверный тип вызывают исключение Lua. Операция заменяет прежний флаг инверсии каждого внутреннего объекта, включая флаги `!` из правил. Инверсия действует только на семейства адресов исходного правила и не сопоставляет недопустимые IP.

Установленное состояние инверсии сохраняется в текущем объекте сопоставления. Если последующие вызовы Hook повторно используют этот объект, изменённое состояние продолжает действовать. См. [Состояние в экземплярах пула](../guide/lifecycle.md#состояние-в-экземплярах-пула).

**Пример**

После инверсии `10.0.0.0/8` сопоставляются допустимые адреса IPv4 вне этого диапазона:

```lua
local ipMatcherObj = geodata.BuildIPMatcher("10.0.0.0/8")
ipMatcherObj:SetReverse(true)
```

#### ToggleReverse

```lua
ipMatcherObj:ToggleReverse()
```

Переключает флаг инверсии каждого внутреннего объекта сопоставления.

**Параметры**

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

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

Нет возвращаемых значений.

**Поведение**

Каждый внутренний объект в сочетании правил переключает собственный флаг инверсии. Результат не равнозначен логическому отрицанию всего сочетания.
Новое состояние инверсии сохраняется в текущем объекте сопоставления. Если последующие вызовы Hook повторно используют этот объект, изменённое состояние продолжает действовать. См. [Состояние в экземплярах пула](../guide/lifecycle.md#состояние-в-экземплярах-пула).