Перейти к содержанию

jit-uuid: Быстрая библиотека UUID без зависимостей для LuaJIT/nginx-module-lua

Установка

Если вы еще не подписались на репозиторий 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-jit-uuid

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

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

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

Этот документ описывает lua-resty-jit-uuid v0.0.7, выпущенный 16 декабря 2017 года.

[![Module Version][badge-version-image]][luarocks-resty-jit-uuid] [![Coverage Status][badge-coveralls-image]][badge-coveralls-url]

Чистая библиотека UUID для LuaJIT (без зависимостей), настроенная для производительности.

Мотивация

Этот модуль нацелен на то, чтобы быть библиотекой UUID без зависимостей, производительной и полной для LuaJIT и ngx_lua.

В отличие от FFI и C привязок, он не зависит от наличия libuuid в вашей системе. Более того, он работает лучше большинства (всех?) генераторов, с которыми проводились бенчмарки, включая FFI привязки.

Наконец, он предоставляет дополнительные функции, такие как генерация UUID v3/v4/v5 и валидация UUID.

Смотрите раздел Бенчмарки для сравнений с другими библиотеками UUID для Lua/LuaJIT.

Использование

LuaJIT: 

local uuid = require 'resty.jit-uuid'

uuid.seed()        ---> автоматическая инициализация с os.time(), LuaSocket или ngx.time()

uuid()             ---> v4 UUID (случайный)
uuid.generate_v4() ---> v4 UUID

uuid.generate_v3() ---> v3 UUID (на основе имени с MD5)
uuid.generate_v5() ---> v5 UUID (на основе имени с SHA-1)

uuid.is_valid()    ---> true/false (автоматические JIT PCRE или Lua шаблоны)

OpenResty: 

http {
    init_worker_by_lua_block {
        local uuid = require 'resty.jit-uuid'
        uuid.seed() -- очень важно!
    }

    server {
        location / {
            content_by_lua_block {
                local uuid = require 'resty.jit-uuid'
                ngx.say(uuid())
            }
        }
    }
}

Примечание: при генерации v4 (случайных) UUID в ngx_lua очень важно, чтобы вы инициализировали этот модуль на этапе init_worker. Если вы этого не сделаете, ваши рабочие процессы будут генерировать идентичные последовательности UUID, что может привести к серьезным проблемам в вашем приложении. Требование инициализации также применяется в случаях, выходящих за рамки ngx_lua, хотя инициализация в таких случаях менее критична. Кроме того, вам следует быть осторожными с использованием директивы lua_code_cache: если кэш Lua-кода отключен, все последовательности сгенерированных UUID во время последующих запросов будут идентичными, если этот модуль не инициализирован для каждого запроса. Точно так же, как отключение кэша Lua-кода, такое поведение будет считаться антипаттерном ngx_lua, и вам следует его избегать.

Документация

Документация доступна онлайн по адресу http://thibaultcha.github.io/lua-resty-jit-uuid/.

Бенчмарки

Этот модуль был тщательно протестирован на каждом этапе его реализации, чтобы обеспечить наилучшие показатели производительности для OpenResty и чистого LuaJIT. Например, валидация UUID будет использовать JIT PCRE вместо Lua шаблонов, когда это возможно.

Файл bench.lua предоставляет бенчмарки генерации UUID для нескольких популярных библиотек UUID.

Запустите make bench, чтобы выполнить их: 

LuaJIT 2.1.0-beta1 с 1e+06 UUIDs
Генерация UUID v4 (случайный)
1. resty-jit-uuid   заняла:   0.064228s    0%
2. FFI привязка     заняла:   0.093374s   +45%
3. C привязка       заняла:   0.220542s   +243%
4. Чистый Lua       заняла:   2.051905s   +3094%

Генерация UUID v3 (на основе имени и MD5), если поддерживается
1. resty-jit-uuid   заняла:   1.306127s

Генерация UUID v5 (на основе имени и SHA-1), если поддерживается
1. resty-jit-uuid   заняла:   4.834929s

Валидация UUID, если поддерживается (набор из 70% действительных, 30% недействительных)
1. resty-jit-uuid (JIT PCRE включен)    заняла:   0.223060s
2. FFI привязка                          заняла:   0.256580s
3. resty-jit-uuid (Lua шаблоны)        заняла:   0.444174s

Примечание: производительность валидации UUID в ngx_lua (JIT PCRE) может быть значительно улучшена путем включения lua-resty-core.

Вклад

Предложения по улучшению производительности этого модуля или бенчмарков (любой протестированной библиотеки) особенно приветствуются.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-jit-uuid.