core: Nouvelle API basée sur FFI pour lua-nginx-module

Installation

Si vous n'avez pas configuré l'abonnement au dépôt RPM, inscrivez-vous. Ensuite, vous pouvez procéder avec les étapes suivantes.

CentOS/RHEL 7 ou 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

Pour utiliser cette bibliothèque Lua avec NGINX, assurez-vous que nginx-module-lua est installé.

Ce document décrit lua-resty-core v0.1.32.post1 publié le 13 décembre 2025.

Cette bibliothèque est automatiquement chargée par défaut depuis OpenResty 1.15.8.1. Ce comportement peut être désactivé via la directive lua_load_resty_core, mais notez que l'utilisation de cette bibliothèque est vivement recommandée, car son implémentation FFI est à la fois plus rapide, plus sûre et plus complète que l'API C Lua du module ngx_lua.

Si vous utilisez une version plus ancienne d'OpenResty, vous devez charger cette bibliothèque comme suit :

    # nginx.conf

    http {
        # vous n'avez PAS besoin de configurer la ligne suivante lorsque vous
        # utilisez le bundle OpenResty 1.4.3.9+.
        init_by_lua_block {
            require "resty.core"
            collectgarbage("collect")  -- juste pour collecter les déchets
        }

        ...
    }

Description

Cette bibliothèque Lua pure réimplémente une partie de l'API Nginx pour Lua du module ngx_lua avec LuaJIT FFI et installe la nouvelle API Lua basée sur FFI dans les espaces de noms ngx. et ndk. utilisés par le module ngx_lua.

De plus, cette bibliothèque Lua implémente toutes les nouvelles API Lua significatives du module ngx_lua en tant que modules Lua appropriés, comme ngx.semaphore et ngx.balancer.

L'API Lua basée sur FFI peut fonctionner avec le compilateur JIT de LuaJIT. L'API par défaut de ngx_lua est basée sur l'API C Lua standard, qui ne sera jamais compilée JIT et le code Lua utilisateur est toujours interprété (lentement).

Le support pour le nouveau ngx_stream_lua_module a également commencé.

Cette bibliothèque est livrée avec le bundle OpenResty par défaut. Vous n'avez donc pas vraiment besoin de vous soucier des dépendances et des exigences.

Prérequis

AVERTISSEMENT Cette bibliothèque est incluse avec chaque version d'OpenResty. Vous devez utiliser la version intégrée de cette bibliothèque dans la version particulière d'OpenResty que vous utilisez. Sinon, vous pourriez rencontrer de graves problèmes de compatibilité.

LuaJIT 2.1 (pour l'instant, c'est la branche git v2.1 dans le dépôt git officiel 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 Implémentées

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

syntaxe : ctx = resty.core.ctx.get_ctx_table(ctx?)

Semblable à ngx.ctx mais elle accepte un argument ctx optionnel. Elle utilisera le ctx de l'appelant au lieu de créer une nouvelle table lorsque la table ctx n'existe pas.

Remarque : la table ctx sera utilisée pendant tout le cycle de vie de la requête actuelle. Veuillez faire très attention lorsque vous essayez de réutiliser la table ctx. Vous devez vous assurer qu'aucun code Lua n'utilise ou n'est sur le point d'utiliser la table ctx dans la requête actuelle avant de réutiliser la table ctx ailleurs.

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 (getter seulement)

ngx.semaphore

Ce module Lua implémente une API de sémaphore pour une synchronisation efficace des "threads légers", qui peut fonctionner à travers différentes requêtes (mais pas à travers les processus de travail nginx).