Окружение песочницы LuaWorker
Скрипты исполняются в изолированном контейнере Lua 5.4 с кастомной защищенной песочницей sbox. Для обеспечения безопасности многопользовательской среды и защиты от зависаний глобальное пространство изолировано:
- Отключены небезопасные модули:
io.*,os.execute,os.remove,os.rename,package.*,require(доступны только предварительно зарегистрированные сервисные библиотеки); - Защита от бесконечных циклов: лимит на 50 000 000 инструкций на один запуск задачи;
- Лимит на размер строк: не более 1 МБ (
1 048 576байт) на одну операцию со строками; - Безопасная обработка ошибок: функция
pcallзаменена наsafe_pcall, которая никогда не маскирует критическое превышение инструкций или памяти.
Ниже приведен полный перечень встроенных библиотек, доступных напрямую в глобальной области каждого скрипта.
1. HTTP-клиент (http)
Выполняет исходящие синхронные запросы к внешним веб-серверам и REST API.
Базовый вызов: http(options) или http.request(options)
local resp = http({
url = "https://api.example.com/v1/users",
method = "POST", -- "GET" (по умолчанию), "POST", "PUT", "DELETE", "PATCH"
headers = {
["Authorization"] = "Bearer " .. token,
["Content-Type"] = "application/json"
},
body = json.encode({ name = "John" }),
timeout = 15 -- Таймаут в секундах (по умолчанию: 10, максимум: 30)
})
if resp.ok and resp.status == 200 then
local data = json.decode(resp.body)
-- обработка
else
error("Ошибка API: " .. tostring(resp.status) .. " " .. tostring(resp.body))
end
Структура ответа resp:
resp.ok(boolean):true, если HTTP-запрос завершился успешно (сетевой сокет открыт, ответ получен, статус < 500);resp.status(number): HTTP-код ответа сервера (200,201,400,404и т.д.);resp.headers(table): заголовки ответа сервера в нижнем регистре;resp.body(string): сырое тело ответа;resp.error(string | nil): описание сетевой ошибки в случае неудачи (таймаут, DNS failure, connection refused).
Вспомогательные методы:
http.urlencode(data): кодирует строку или ассоциативную таблицу в форматapplication/x-www-form-urlencoded.local query = http.urlencode({ client_id = "123", redirect_uri = "https://example.com" }) -- "client_id=123&redirect_uri=https%3A%2F%2Fexample.com"http.urldecode(string): декодирует percent-encoded строку.http.parse_form(body_string): парсит тело формыa=1&b=2в Lua-таблицу.
2. Работа с JSON (json)
Высокоскоростной парсер и сериализатор на базе C-библиотеки cjson.
json.encode(table): сериализует Lua-таблицу в валидную JSON-строку.local payload_str = json.encode({ status = "active", count = 5 })json.decode(string): парсит JSON-строку в Lua-таблицу. Если строка невалидна, вызывает ошибку (рекомендуется оборачивать вpcall).local ok, data = pcall(json.decode, resp.body) if ok and type(data) == "table" then print(data.result) end
3. Криптография и хеширование (crypto)
Реализована поверх системного OpenSSL (luaossl) с оптимизированными чистыми Lua-энкодерами.
Хеширование и контрольные суммы:
crypto.sha256(str)— SHA-256 хеш в виде hex-строки (64 символа);crypto.sha512(str)— SHA-512 хеш в виде hex-строки (128 символов);crypto.sha1(str)— SHA-1 хеш в виде hex-строки;crypto.md5(str)— MD5 хеш в виде hex-строки.
HMAC (подписи запросов и валидация вебхуков):
crypto.hmac_sha256(key, message)— вычисление подписи HMAC-SHA256 (hex);crypto.hmac_sha512(key, message)— вычисление подписи HMAC-SHA512 (hex).
Пример валидации подписи CryptoBot:
local secret_key = crypto.sha256(token)
local calculated_signature = crypto.hmac_sha256(secret_key, ctx.request.body)
if calculated_signature == received_signature then
-- вебхук подлинный
end
Кодирование данных:
crypto.base64_encode(binary_or_str)— кодирование в Base64;crypto.base64_decode(b64_str)— декодирование из Base64;crypto.hex(binary_data)— преобразование байтовой строки в hex;crypto.url_encode(str)/crypto.url_decode(str).
4. Быстрый распределённый кэш (cache)
Предоставляет доступ к быстрому key-value хранилищу (Valkey / Redis). Все ключи скрипта автоматически изолируются префиксом. Идеально для кэширования временных JWT/Bearer токенов сессий администратора внешних панелей (Marzban, 3x-ui, Proxmox).
cache.get(key)— получить строковое значение по ключу (илиnil, если ключ отсутствует или истёк).local token = cache.get("admin_token:node_1")cache.set(key, value, [ttl_seconds])— сохранить значение с опциональным временем жизни в секундах.-- Сохранить токен на 30 минут cache.set("admin_token:node_1", token, 1800)cache.del(key)— удалить ключ из кэша (например, при получении 401 Unauthorized для принудительного обновления).cache.del("admin_token:node_1")cache.incr(key)— атомарно увеличить целочисленный счётчик на 1.
5. Взаимодействие с ядром платформы (billing)
Позволяет скрипту выполнять системные операции ядра биллинга через защищенный внутренний сокет.
billing.import_keys(service_or_slug, keys_array)
Используется для автоматического импорта пула цифровых лицензионных ключей или кодов активации, полученных оптом от внешнего поставщика.
local res = billing.import_keys("steam-gift-cards", {
"XXXX-YYYY-ZZZZ-0001",
"XXXX-YYYY-ZZZZ-0002",
"XXXX-YYYY-ZZZZ-0003"
})
if res.ok then
log.info(string.format("Импортировано: %d ключей, дубликатов: %d", res.imported, res.duplicates))
end
billing.send_email(options)
Отправка персонализированного письма пользователю с рендерингом на стороне ядра через шаблонизатор Jinja2.
billing.send_email({
to = "buyer@example.com",
template = "vpn_welcome_instructions", -- слаг шаблона из админки
context = {
username = "user_42",
subscription_url = "https://..."
}
})
6. Логирование выполнения (log)
Все записи логов собираются воркером и сохраняются в базе данных SaviorBill с привязкой к конкретной транзакции или услуге. Они мгновенно отображаются в админ-панели в разделе Система → Аудит:
log("Скрипт запущен для действия: " .. tostring(ctx.action)) -- эквивалентно log.info
log.info("Авторизация в Marzban успешна")
log.warn("Повторная попытка запроса из-за тайм-аута")
log.error("Критическая ошибка создания пользователя: " .. tostring(err))
7. Стандартная библиотека Lua
В песочнице полностью доступны следующие стандартные функции и библиотеки Lua:
- Математика (
math):math.floor,math.ceil,math.random,math.randomseed,math.max,math.min,math.absи др. - Строки (
string):string.format,string.sub,string.gsub,string.find,string.match,string.gmatch,string.byte,string.char,string.lower,string.upper,string.len. - Таблицы (
table):table.insert,table.remove,table.concat,table.sort,table.pack,table.unpack. - Время (
os):os.time()(текущий Unix timestamp в секундах),os.date([format, time]). - Базовые функции:
tostring,tonumber,pairs,ipairs,type,assert,error,pcall,xpcall.