resty.uuid

Generate Functions

• generate ()
• generate_random ()
• generate_time ()
• generate_time_safe ()
• generate_time_v6 ()
• generate_time_v7 ()

Time Extraction

• time (id)

Type / Variant Functions

• type (id)
• variant (id)

Validation Functions

• is_valid (id)

Metamethods

• __call ()

Modules

• resty.uuid

Module resty.uuid

LuaJIT FFI bindings to UUID library

Generate Functions

generate ()

Generates a new UUID.

Picks the best available generator on the host: prefers a high-quality randomness source (v4) when available, otherwise falls back to a time-based UUID (v1).

Returns:

string a 36-character canonical UUID (e.g. "f81d4fae-7dec-11d0-a765-00a0c91e6bf6").

Usage:

local uuid = require("resty.uuid")
local id = uuid.generate()

generate_random ()

Generates a random (version 4) UUID.

Uses the system’s cryptographic random source. If high-quality randomness is unavailable, libuuid falls back to a pseudo-random generator.

Returns:

string a 36-character canonical v4 UUID.

Usage:

local uuid = require("resty.uuid")
local id = uuid.generate_random()

generate_time ()

Generates a time-based (version 1) UUID.

Encodes the current timestamp and the host’s MAC address (or a random node id when no MAC is available).

Returns:

string a 36-character canonical v1 UUID.

Usage:

local uuid = require("resty.uuid")
local id = uuid.generate_time()

generate_time_safe ()

Generates a time-based (version 1) UUID and reports whether generation was uniqueness-safe.

The safe flag indicates whether libuuid was able to use synchronization (typically via uuidd) to guarantee uniqueness across concurrent callers. A value of false means the UUID is still well-formed but may collide if the same node generates many UUIDs in the same clock tick from multiple processes.

Returns:

1. string a 36-character canonical v1 UUID.
2. boolean true if generation was synchronized/safe, false otherwise.

Usage:

local uuid = require("resty.uuid")
local id, safe = uuid.generate_time_safe()

generate_time_v6 ()

Generates a reordered time-based (version 6) UUID.

Version 6 reorders the v1 timestamp fields so the UUID sorts naturally in lexical order, while remaining compatible with v1 node/clock semantics.

Returns:

string a 36-character canonical v6 UUID.

Usage:

local uuid = require("resty.uuid")
local id = uuid.generate_time_v6()

generate_time_v7 ()

Generates a Unix-epoch time-based (version 7) UUID.

Version 7 encodes a millisecond-resolution Unix timestamp followed by random bits, and sorts naturally in lexical order.

Returns:

string a 36-character canonical v7 UUID.

Usage:

local uuid = require("resty.uuid")
local id = uuid.generate_time_v7()

Time Extraction

time (id)

Extracts the timestamp embedded in a time-based UUID.

Only meaningful for v1, v6 and v7 UUIDs. For other versions the result is the value libuuid synthesizes from the bits and is not a real time.

Parameters:

• id string a UUID string to inspect.

Returns:

1. optional number seconds since the Unix epoch, or nil if id is not a valid UUID.
2. optional number microseconds within that second.

Usage:

local uuid = require("resty.uuid")
local secs, usecs = uuid.time(id)

Type / Variant Functions

type (id)

Returns the UUID type (version) of a UUID string.

The returned integer corresponds to libuuid’s UUID_TYPE_* constants (1 = DCE time/v1, 4 = DCE random/v4, 6 = v6, 7 = v7, etc.).

Parameters:

• id string a UUID string to inspect.

Returns:

optional int the UUID type, or nil if id is not a valid UUID.

Usage:

local uuid = require("resty.uuid")
local t = uuid.type("f81d4fae-7dec-11d0-a765-00a0c91e6bf6") --> 1

variant (id)

Returns the UUID variant of a UUID string.

The returned integer corresponds to libuuid’s UUID_VARIANT_* constants (0 = NCS, 1 = DCE, 2 = Microsoft, 3 = other/reserved).

Parameters:

• id string a UUID string to inspect.

Returns:

optional int the UUID variant, or nil if id is not a valid UUID.

Usage:

local uuid = require("resty.uuid")
local v = uuid.variant("f81d4fae-7dec-11d0-a765-00a0c91e6bf6") --> 1

Validation Functions

is_valid (id)

Tests whether a string is a syntactically valid UUID.

Accepts the canonical 36-character 8-4-4-4-12 hex form in either case. Does not check the version or variant fields beyond what libuuid’s parser requires.

Parameters:

• id string the candidate UUID string.

Returns:

boolean true if id parses as a UUID, false otherwise.

Usage:

local uuid = require("resty.uuid")
if uuid.is_valid(s) then
  ...
end

Metamethods

__call ()

Calls the module as a shortcut for uuid.generate.

Lets you write uuid() instead of uuid.generate().

Returns:

string a 36-character canonical UUID.

Usage:

local uuid = require("resty.uuid")'
local id = uuid()