{"id":17921986,"url":"https://github.com/thibaultcha/lua-resty-jit-uuid","last_synced_at":"2025-03-24T02:32:08.481Z","repository":{"id":152276805,"uuid":"54528071","full_name":"thibaultcha/lua-resty-jit-uuid","owner":"thibaultcha","description":"Fast and dependency-free UUID library for LuaJIT/ngx_lua","archived":false,"fork":false,"pushed_at":"2020-01-10T02:28:06.000Z","size":89,"stargazers_count":205,"open_issues_count":1,"forks_count":40,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-04-14T20:01:54.513Z","etag":null,"topics":["lua-resty","luajit","ngx-lua","openresty","uuid"],"latest_commit_sha":null,"homepage":"http://thibaultcha.github.io/lua-resty-jit-uuid/","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thibaultcha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-03-23T03:29:15.000Z","updated_at":"2024-03-05T07:41:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"d42ae668-868d-4d83-99ef-5cb217736f21","html_url":"https://github.com/thibaultcha/lua-resty-jit-uuid","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-resty-jit-uuid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-resty-jit-uuid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-resty-jit-uuid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-resty-jit-uuid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thibaultcha","download_url":"https://codeload.github.com/thibaultcha/lua-resty-jit-uuid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245198661,"owners_count":20576410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lua-resty","luajit","ngx-lua","openresty","uuid"],"created_at":"2024-10-28T20:37:03.850Z","updated_at":"2025-03-24T02:32:08.205Z","avatar_url":"https://github.com/thibaultcha.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lua-resty-jit-uuid\n\n[![Module Version][badge-version-image]][luarocks-resty-jit-uuid]\n[![Build Status][badge-travis-image]][badge-travis-url]\n[![Coverage Status][badge-coveralls-image]][badge-coveralls-url]\n\nA pure LuaJIT (no dependencies) UUID library tuned for performance.\n\n### Table of Contents\n\n* [Motivation](#motivation)\n* [Usage](#usage)\n* [Installation](#installation)\n* [Documentation](#documentation)\n* [Benchmarks](#benchmarks)\n* [Contributions](#contributions)\n* [License](#license)\n\n### Motivation\n\nThis module is aimed at being a free of dependencies, performant and\ncomplete UUID library for LuaJIT and ngx_lua.\n\nUnlike FFI and C bindings, it does not depend on libuuid being available\nin your system. On top of that, it performs **better** than most (all?)\nof the generators it was benchmarked against, FFI bindings included.\n\nFinally, it provides additional features such as UUID v3/v4/v5 generation and\nUUID validation.\n\nSee the [Benchmarks](#benchmarks) section for comparisons between other UUID\nlibraries for Lua/LuaJIT.\n\n[Back to TOC](#table-of-contents)\n\n### Usage\n\nLuaJIT:\n```lua\nlocal uuid = require 'resty.jit-uuid'\n\nuuid.seed()        ---\u003e automatic seeding with os.time(), LuaSocket, or ngx.time()\n\nuuid()             ---\u003e v4 UUID (random)\nuuid.generate_v4() ---\u003e v4 UUID\n\nuuid.generate_v3() ---\u003e v3 UUID (name-based with MD5)\nuuid.generate_v5() ---\u003e v5 UUID (name-based with SHA-1)\n\nuuid.is_valid()    ---\u003e true/false (automatic JIT PCRE or Lua patterns)\n```\n\nOpenResty:\n```nginx\nhttp {\n    init_worker_by_lua_block {\n        local uuid = require 'resty.jit-uuid'\n        uuid.seed() -- very important!\n    }\n\n    server {\n        location / {\n            content_by_lua_block {\n                local uuid = require 'resty.jit-uuid'\n                ngx.say(uuid())\n            }\n        }\n    }\n}\n```\n\n**Note**: when generating v4 (random) UUIDs in ngx_lua, it is **very\nimportant** that you seed this module in the `init_worker` phase. If you do\nnot, your workers will generate identical UUID sequences, which could lead to\nserious issues in your application. The seeding requirement also applies in\nuses outside of ngx_lua, although seeding is less delicate in such cases.\nAdditionally, you should be weary about the usage of the\n[`lua_code_cache`](https://github.com/openresty/lua-nginx-module#lua_code_cache)\ndirective: if Lua code cache is disabled, all sequences of UUIDs generated\nduring subsequent requests will be identical, unless this module is seeded for\nevery request. Just like disabling Lua code cache, such behavior would be\nconsidered an ngx_lua anti-pattern and you should avoid it.\n\n[Back to TOC](#table-of-contents)\n\n### Installation\n\nThis module can be installed through Luarocks:\n```bash\n$ luarocks install lua-resty-jit-uuid\n```\n\nOr via [opm](https://github.com/openresty/opm):\n```bash\n$ opm get thibaultcha/lua-resty-jit-uuid\n```\n\nOr can be manually copied in your `LUA_PATH`.\n\n[Back to TOC](#table-of-contents)\n\n### Documentation\n\nDocumentation is available online at\n\u003chttp://thibaultcha.github.io/lua-resty-jit-uuid/\u003e.\n\n[Back to TOC](#table-of-contents)\n\n### Benchmarks\n\nThis module has been carefully benchmarked on each step of its implementation\nto ensure the best performance for OpenResty and plain LuaJIT. For example,\nUUID validation will use JIT PCRE over Lua patterns when possible.\n\nThe `bench.lua` file provides benchmarks of UUID generation for several popular\nUUID libraries.\n\nRun `make bench` to run them:\n```\nLuaJIT 2.1.0-beta1 with 1e+06 UUIDs\nUUID v4 (random) generation\n1. resty-jit-uuid   took:   0.064228s    0%\n2. FFI binding      took:   0.093374s   +45%\n3. C binding        took:   0.220542s   +243%\n4. Pure Lua         took:   2.051905s   +3094%\n\nUUID v3 (name-based and MD5) generation if supported\n1. resty-jit-uuid   took:   1.306127s\n\nUUID v5 (name-based and SHA-1) generation if supported\n1. resty-jit-uuid   took:   4.834929s\n\nUUID validation if supported (set of 70% valid, 30% invalid)\n1. resty-jit-uuid (JIT PCRE enabled)    took:   0.223060s\n2. FFI binding                          took:   0.256580s\n3. resty-jit-uuid (Lua patterns)        took:   0.444174s\n```\n\n* FFI binding: \u003chttps://github.com/bungle/lua-resty-uuid\u003e\n* C binding: \u003chttps://github.com/Mashape/lua-uuid\u003e\n* Pure Lua: \u003chttps://github.com/Tieske/uuid\u003e\n* resty-jit-uuid: this module (base reference for generation % comparison)\n\n**Note**: UUID validation performance in ngx_lua (JIT PCRE) can be greatly\nimproved by enabling\n[lua-resty-core](https://github.com/openresty/lua-resty-core).\n\n[Back to TOC](#table-of-contents)\n\n### Contributions\n\nSuggestions improving this module's or the benchmarks' performance\n(of any benchmarked library) are particularly appreciated.\n\n[Back to TOC](#table-of-contents)\n\n### License\n\nWork licensed under the MIT License.\n\n[Back to TOC](#table-of-contents)\n\n[luarocks-resty-jit-uuid]: http://luarocks.org/modules/thibaultcha/lua-resty-jit-uuid\n\n[badge-travis-url]: https://travis-ci.org/thibaultcha/lua-resty-jit-uuid\n[badge-travis-image]: https://travis-ci.org/thibaultcha/lua-resty-jit-uuid.svg?branch=master\n\n[badge-coveralls-url]: https://coveralls.io/r/thibaultcha/lua-resty-jit-uuid?branch=master\n[badge-coveralls-image]: https://coveralls.io/repos/thibaultcha/lua-resty-jit-uuid/badge.svg?branch=master\u0026style=flat\n\n[badge-version-image]: https://img.shields.io/badge/version-0.0.7-blue.svg?style=flat\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthibaultcha%2Flua-resty-jit-uuid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthibaultcha%2Flua-resty-jit-uuid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthibaultcha%2Flua-resty-jit-uuid/lists"}