Utilities
nauthilus_util reads environment variables and writes to the cache, so it cannot be required by environment sources, subject sources, or actions, which run in the Policy VM. It is available in init scripts, custom hooks, and Lua backends. See Lua runtimes and capabilities.
The nauthilus_util module provides several helper functions for Lua scripts in Nauthilus.
local nauthilus_util = require("nauthilus_util")
Functions
nauthilus_util.getenv
Returns the value of an environment variable, cached via nauthilus_cache.
Syntax
local val = nauthilus_util.getenv(name, default)
Parameters
name(string) - The name of the environment variable.default(string) - A default value if the environment variable is not set.
Returns
val(string) - The value of the environment variable or the default value.
Example
local api_url = nauthilus_util.getenv("API_URL", "http://localhost:8080")
nauthilus_util.exists_in_table
Iterates over a flat Lua table (list) and checks if a string was found in the values.
Syntax
local found = nauthilus_util.exists_in_table(tbl, element)
Parameters
tbl(table) - The table to search in.element(string) - The string to search for.
Returns
found(boolean) -trueif found,falseotherwise.
Example
local roles = {"admin", "user", "guest"}
if nauthilus_util.exists_in_table(roles, "admin") then
-- User is an admin
end
nauthilus_util.get_current_timestamp
Creates a timestamp string valid for logging purposes. It respects the TZ environment variable.
Syntax
local ts = nauthilus_util.get_current_timestamp()
Returns
ts(string) - A formatted timestamp string (e.g., "2006-01-02T15:04:05 -07:00").
Example
local timestamp = nauthilus_util.get_current_timestamp()
-- result: "2024-01-21T15:00:00 +01:00"
nauthilus_util.table_length
Calculates the length of a Lua table.
Syntax
local len = nauthilus_util.table_length(tbl)
Parameters
tbl(table) - The table to count.
Returns
len(number) - The number of elements in the table.
Example
local my_table = {a = 1, b = 2, c = 3}
local size = nauthilus_util.table_length(my_table)
-- size: 3
nauthilus_util.if_error_raise
Checks if an error was set and calls the Lua error function to exit script execution. It ignores "redis: nil" or "OK" messages.
Syntax
nauthilus_util.if_error_raise(err)
Parameters
err(string) - The error message to check.
Example
local result, err = nauthilus_redis.redis_get("handle", "my_key")
nauthilus_util.if_error_raise(err)
nauthilus_util.is_table
Returns true if the given parameter is of type table.
Syntax
local result = nauthilus_util.is_table(object)
Parameters
object(any) - The object to check.
Example
local data = {key = "value"}
if nauthilus_util.is_table(data) then
-- It is a table
end
nauthilus_util.is_string
Returns true if the given parameter is of type string.
Syntax
local result = nauthilus_util.is_string(object)
Parameters
object(any) - The object to check.
Example
if nauthilus_util.is_string("hello") then
-- It is a string
end
nauthilus_util.is_number
Returns true if the given parameter is of type number.
Syntax
local result = nauthilus_util.is_number(object)
Parameters
object(any) - The object to check.
Example
if nauthilus_util.is_number(123) then
-- It is a number
end
nauthilus_util.get_redis_key
Returns a Redis key with the prefix from the request, if available.
Syntax
local key = nauthilus_util.get_redis_key(request, key)
Parameters
request(table) - The Nauthilus request object.key(string) - The base Redis key.
Returns
key(string) - The prefixed Redis key.
Example
local key = nauthilus_util.get_redis_key(request, "my_data")
-- result: "nt_:my_data" (if prefix is "nt_")
nauthilus_util.toboolean
Converts a string value into a boolean.
Syntax
local bool = nauthilus_util.toboolean(str)
Parameters
str(string) - The string to convert.
Returns
bool(boolean) -falseif the lower-cased string is "false", "0", or empty.trueotherwise.
Example
local is_enabled = nauthilus_util.toboolean("true") -- true
local is_disabled = nauthilus_util.toboolean("0") -- false
nauthilus_util.generate_random_string
Creates a random string of a specified length.
Syntax
local str = nauthilus_util.generate_random_string(length)
Parameters
length(number) - The desired length of the string.
Returns
str(string) - The random alphanumeric string.
Example
local nonce = nauthilus_util.generate_random_string(16)
nauthilus_util.is_routable_ip
Checks if an IP address is routable on the internet.
Syntax
local routable = nauthilus_util.is_routable_ip(ip)
Parameters
ip(string) - The IP address to check.
Returns
routable(boolean) -trueif routable,falsefor private or reserved ranges.
Example
local ok = nauthilus_util.is_routable_ip("8.8.8.8") -- true
local internal = nauthilus_util.is_routable_ip("192.168.1.1") -- false
Logging Functions
The following functions log messages at different levels. They respect the configured log level and format.
Syntax
nauthilus_util.log_debug(logging, result)
nauthilus_util.log_info(logging, result)
nauthilus_util.log_notice(logging, result)
nauthilus_util.log_warn(logging, result)
nauthilus_util.log_error(logging, result, err_string)
Parameters
logging(table) - The logging configuration object.result(table) - A table of key/value pairs to log.err_string(string) - (Only forlog_error) An additional error message.
Example
local log_data = {
user = request.username,
action = "login",
status = "success"
}
nauthilus_util.log_info(request.logging, log_data)