lua-resty-uuid

May 7, 2026 · View on GitHub

LuaJIT FFI bindings for libuuid — a DCE-compatible Universally Unique Identifier (UUID/GUID) library. Generates v1 (time), v4 (random), v6 (reordered time) and v7 (Unix-epoch) UUIDs, plus parses and inspects existing UUID strings.

Status

Production-ready. Used in OpenResty / LuaJIT environments. Pure FFI bindings — no C build step required, just libuuid on the system.

Requirements

LuaJIT (or Lua 5.1+ with the luaffi shim)
libuuid available on the dynamic loader path
- Debian / Ubuntu: apt install uuid-dev (provides libuuid.so)
- Alpine: apk add util-linux-dev
- RHEL / Fedora: dnf install libuuid-devel
- macOS: bundled with the system (loaded from libSystem)

Installation

Via LuaRocks

luarocks install lua-resty-uuid

From source

git clone https://github.com/bungle/lua-resty-uuid
cd lua-resty-uuid
luarocks make

The library will look for libuuid first in package.cpath, then on the system loader path, falling back to symbols already present in the host process.

Quick start

local uuid = require "resty.uuid"

uuid.generate()         --> "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
uuid.generate_random()  --> "550e8400-e29b-41d4-a716-446655440000"  (v4)
uuid.generate_time()    --> "..."                                   (v1)
uuid.generate_time_v6() --> "..."                                   (v6)
uuid.generate_time_v7() --> "..."                                   (v7)

uuid()                  --> shortcut for uuid.generate()

uuid.is_valid("not-a-uuid")  --> false
uuid.type(some_v4_id)        --> 4
uuid.variant(some_id)        --> 1   (DCE)
uuid.time(some_v1_id)        --> 1714867200, 123456

API

The module is a table that is also callable. Calling uuid() is a shortcut for uuid.generate().

Generators

Function	Returns	Description
`uuid.generate()`	`string`	Best generator available on the host (random when possible, otherwise time-based).
`uuid.generate_random()`	`string`	Version 4 (random) UUID.
`uuid.generate_time()`	`string`	Version 1 (timestamp + node id) UUID.
`uuid.generate_time_safe()`	`string, boolean`	Version 1 UUID and a flag indicating whether generation was synchronized for uniqueness.
`uuid.generate_time_v6()`	`string`	Version 6 UUID — v1 fields reordered for lexical sortability.
`uuid.generate_time_v7()`	`string`	Version 7 UUID — millisecond Unix timestamp + random tail.

All generators return the canonical 36-character 8-4-4-4-12 lower-case hex form, e.g. "f81d4fae-7dec-11d0-a765-00a0c91e6bf6".

Inspection

Function	Returns	Description
`uuid.is_valid(id)`	`boolean`	Whether `id` parses as a UUID.
`uuid.type(id)`	`int` or `nil`	UUID version (`UUID_TYPE_*` constant), or `nil` if invalid.
`uuid.variant(id)`	`int` or `nil`	UUID variant (`UUID_VARIANT_*` constant), or `nil` if invalid.
`uuid.time(id)`	`number, number` or `nil`	Seconds since the Unix epoch and microseconds within that second; `nil` if `id` is not a valid UUID. Meaningful only for v1, v6 and v7.

Constant reference

uuid.type returns one of:

Value	Constant	Meaning
`1`	`UUID_TYPE_DCE_TIME`	Time-based (v1)
`2`	`UUID_TYPE_DCE_SECURITY`	DCE Security (v2)
`3`	`UUID_TYPE_DCE_MD5`	Name-based MD5 (v3)
`4`	`UUID_TYPE_DCE_RANDOM`	Random (v4)
`5`	`UUID_TYPE_DCE_SHA1`	Name-based SHA-1 (v5)
`6`	`UUID_TYPE_DCE_TIME_V6`	Reordered time (v6)
`7`	`UUID_TYPE_DCE_TIME_V7`	Unix-epoch time (v7)

uuid.variant returns one of:

Value	Constant	Meaning
`0`	`UUID_VARIANT_NCS`	NCS / Apollo legacy
`1`	`UUID_VARIANT_DCE`	DCE 1.1 / RFC 4122
`2`	`UUID_VARIANT_MICROSOFT`	Microsoft GUID
`3`	`UUID_VARIANT_OTHER`	Reserved

Testing

make test          # full pipeline: install rock, run busted, coverage, lint
make unit          # busted only
make coverage      # busted + luacov report
make lint          # luacheck

Tests live in spec/ and exercise every public function plus the __call metamethod.

Documentation

API reference is built with LDoc and lives under docs/:

make docs

License

BSD 2-Clause. See LICENSE.