core: Новый API на основе FFI для lua-nginx-module

Установка

Если вы еще не подписались на RPM-репозиторий, зарегистрируйтесь. После этого вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-core

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-core

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-core v0.1.32.post1, выпущенный 13 декабря 2025 года.

Эта библиотека автоматически загружается по умолчанию с версии OpenResty 1.15.8.1. Это поведение можно отключить с помощью директивы lua_load_resty_core, но обратите внимание, что использование этой библиотеки настоятельно рекомендуется, так как ее реализация FFI быстрее, безопаснее и более полная, чем Lua C API модуля ngx_lua.

Если вы используете более старую версию OpenResty, вам нужно загрузить эту библиотеку следующим образом:

    # nginx.conf

    http {
        # вам НЕ нужно настраивать следующую строку, когда вы
        # используете пакет OpenResty 1.4.3.9+.
        init_by_lua_block {
            require "resty.core"
            collectgarbage("collect")  -- просто для сбора мусора
        }

        ...
    }

Описание

Эта чистая библиотека Lua повторно реализует часть ngx_lua модуля Nginx API для Lua с помощью LuaJIT FFI и устанавливает новый Lua API на основе FFI в пространства имен ngx. и ndk., используемые модулем ngx_lua.

Кроме того, эта библиотека Lua реализует любые значительные новые Lua API модуля ngx_lua как полноценные модули Lua, такие как ngx.semaphore и ngx.balancer.

Lua API на основе FFI может работать с JIT-компилятором LuaJIT. Стандартный API ngx_lua основан на стандартном Lua C API, который никогда не будет JIT-компилироваться, и пользовательский код Lua всегда интерпретируется (медленно).

Поддержка нового ngx_stream_lua_module также началась.

Эта библиотека поставляется с пакетом OpenResty по умолчанию. Поэтому вам не нужно беспокоиться о зависимостях и требованиях.

Предварительные требования

ПРЕДУПРЕЖДЕНИЕ Эта библиотека включена в каждую версию OpenResty. Вы должны использовать встроенную версию этой библиотеки в конкретной версии OpenResty, которую вы используете. В противном случае вы можете столкнуться с серьезными проблемами совместимости.

LuaJIT 2.1 (на данный момент это ветка v2.1 в официальном репозитории luajit-2.0: http://luajit.org/download.html)
ngx_http_lua_module v0.10.25.
ngx_stream_lua_module v0.0.13.
lua-resty-lrucache

Реализованный API

resty.core.hash

resty.core.base64

resty.core.uri

resty.core.regex

resty.core.exit

ngx.exit

resty.core.shdict

resty.core.var

ngx.var.VARIABLE

resty.core.ctx

ngx.ctx

get_ctx_table

синтаксис: ctx = resty.core.ctx.get_ctx_table(ctx?)

Похож на ngx.ctx, но принимает необязательный аргумент ctx. Он будет использовать ctx из вызывающего кода вместо создания новой таблицы, когда таблица ctx не существует.

Обратите внимание: таблица ctx будет использоваться на протяжении всего жизненного цикла текущего запроса. Пожалуйста, будьте очень осторожны, когда вы пытаетесь повторно использовать таблицу ctx. Вам нужно убедиться, что нет кода Lua, использующего или собирающегося использовать таблицу ctx в текущем запросе, прежде чем повторно использовать таблицу ctx в другом месте.

resty.core.request

resty.core.response

ngx.header.HEADER

resty.core.misc

resty.core.time

resty.core.worker

resty.core.phase

ngx.get_phase

resty.core.ndk

ndk.set_var

resty.core.socket

resty.core.param

ngx.arg (только геттер)

ngx.semaphore

Этот модуль Lua реализует API семафора для эффективной синхронизации "легких потоков", который может работать между разными запросами (но не между процессами рабочего nginx).