Типы данных

На этой странице собраны типы данных, общие для модулей, и описаны их представление и использование в Lua. Типы, специфичные для отдельного модуля, описаны на его странице.

net.IP

Свойство	Описание
Базовый тип Go	net.IP, common/net.IP
Представление в Lua	userdata

Обычно не нужно сравнивать значения net.IP по одному в Lua, особенно в часто выполняемом коде. Для сопоставления IP используйте прежде всего IPMatcher, который напрямую работает со значениями net.IP, возвращаемыми API.

Если нужно работать с IP напрямую, учитывайте, что net.IP и строка IP-адреса — разные типы. Для преобразования и сравнения доступны следующие два метода:

String

local text = ip:String()

Преобразует IP в текст адреса.

Параметры

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

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

Значение	Тип	Описание
text	string	Строка IP-адреса; никогда не nil

Equal

local equal = ip:Equal(otherIP)

Проверяет равенство двух IP.

Параметры

Параметр	Тип	Описание
otherIP	net.IP или nil	IP для сравнения; допускается явный nil

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

Значение	Тип	Описание
equal	boolean	true при равенстве, иначе false; никогда не nil

Поведение

Сравнение допустимого IP с nil возвращает false.

Пример

if ip ~= nil then
    local text = ip:String()
    local equal = ip:Equal(otherIP)
end

slice

Срез Go представлен в Lua как userdata, сохраняет тип элементов и индексируется начиная с 1. Следующие два типа срезов используют одинаковые операции получения длины, доступа по индексу и перебора.

Тип	Представление в Lua	Тип элемента
[]net.IP	userdata	net.IP
[]uint32	userdata	number

[]net.IP

Совет: для сопоставления или фильтрации списков IP используйте прежде всего IPMatcher, который напрямую работает с []net.IP.

[]uint32

Элементы — 32-битные целые числа без знака в диапазоне 0 .. 4294967295.

#values

local count = #values

Возвращает число элементов среза.

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

Значение	Тип	Описание
count	number	Неотрицательное целое число; 0 для пустого среза

Поведение

Списки, возвращаемые API, могут быть nil или срезами длины 0. Перед выполнением этих операций values не должен быть nil; одной проверки if values then недостаточно, чтобы определить наличие элементов.

values[i]

local value = values[i]

Читает один элемент среза.

Параметры

Параметр	Тип	Описание
i	number	Обязателен; целое число в диапазоне 1 .. #values

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

Значение	Тип	Описание
value	net.IP или number	Элемент []net.IP или []uint32 соответственно

Поведение

Выход за границы вызывает исключение Lua, а не возвращает nil. Избегайте прямого изменения срезов, возвращаемых API.

Пример

if ips ~= nil and #ips > 0 then
    local firstIP = ips[1]:String()
end

values()

for i, value in values() do
    -- Используйте индекс i и элемент value
end

Возвращает итератор среза для обобщённого цикла for; индексы начинаются с 1.

Параметры

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

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

Значение	Тип	Описание
Итератор	function	Последовательно предоставляет индекс и элемент, как показано выше

Поведение

Срезы не поддерживают pairs и ipairs; для перебора также можно использовать числовой цикл for.

Пример

if ips ~= nil then
    for i = 1, #ips do
        local text = ips[i]:String()
    end

    for i, ip in ips() do
        local text = ip:String()
    end
end

Ввод списка IP

При передаче списка IP в IPMatcher доступны следующие формы:

Форма ввода	Представление в Lua	Описание
[]net.IP	userdata	Список IP; допускается пустой срез
Массив net.IP	table	IP последовательно с индекса 1; допускается пустой массив {}, но не пропуски
nil	nil	Нужно передать явно; результат указан в описании каждого метода

Строки IP-адресов не преобразуются в net.IP. Пустая строка "" не является допустимым списком IP; её передача в AnyMatch, Matches или FilterIPs вызывает исключение Lua.

error

Свойство	Описание
Базовый тип Go	error
Представление в Lua	userdata при ошибке; nil при её отсутствии

Если возвращаемое API значение err равно nil, ошибки нет; иначе это объект ошибки. Его можно без изменений вернуть как err из Hook, чтобы передать ошибку ядру Xray.

Соглашение о возврате из Hook

Значение ошибки	Значение
nil	Ошибки нет
userdata ошибки	Сохраняет исходную ошибку
string	Сообщение об ошибке от скрипта; пустая строка "" также означает ошибку

Строковые ошибки допустимы только в возвращаемых значениях Hook. Сами API Xray возвращают ошибку или nil. Проверка значений и поведение при ошибках описаны в соответствующем Hook.

Вывод сообщений об ошибках

Сообщение объекта ошибки Go нельзя получить через tostring(err). Для вывода передайте err напрямую в xray.log.

local log = require("xray.log")
local ips, ttl, err = serverObj:Query(domain, ipv4, ipv6, fake)
if err ~= nil then
    log.Warning("Ошибка DNS-запроса: ", err)
elseif ips ~= nil and #ips > 0 then
    local firstIP = ips[1]:String()
end