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.post3 выпущенный 27 марта 2026 года.

Эта библиотека автоматически загружается по умолчанию с 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 и устанавливает новый API Lua на основе FFI в пространства имен ngx. и ndk. используемые модулем ngx_lua.

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

API Lua на основе 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).