kong.tools.utils

Module containing some general utility functions used in many places in Kong.

NOTE: Before implementing a function here, consider if it will be used in many places across Kong. If not, a local function in the appropriate module is preferred.

Functions

add_error (errors, k, v) Add an error message to a key/value table.
deep_copy (orig) Deep copies a table into a new table.
encode_args (args, raw) Encode a Lua table to a querystring Tries to mimic ngx_lua's ngx.encode_args, but also percent-encode querystring values.
get_hostname () Retrieves the hostname of the local machine
is_array (t) Checks if a table is an array and not an associative array.
load_module_if_exists (module_name) Try to load a module.
random_string () Generates a random unique string
table_contains (arr, val) Checks if a value exists in a table.
table_merge (t1, t2) Merges two table together.
table_size (t) Calculates a table size.

Functions


add_error

Add an error message to a key/value table. If the key already exists, a sub table is created with the original and the new value.
Parameters:
  • errors (Optional) Table to attach the error to. If nil, the table will be created.
  • k Key on which to insert the error in the errors table.
  • v Value of the error
Returns:
  • The errors table with the new error inserted.

deep_copy

Deep copies a table into a new table. Tables used as keys are also deep copied, as are metatables
Parameters:
  • orig The table to copy
Returns:
  • Returns a copy of the input table

encode_args

Encode a Lua table to a querystring Tries to mimic ngx_lua's ngx.encode_args, but also percent-encode querystring values. Supports multi-value query args, boolean values. It also supports encoding for bodies (only because it is used in http_client for specs.
Parameters:
  • args table A key/value table containing the query args to encode.
  • raw boolean If true, will not percent-encode any key/value and will ignore special boolean rules.
Returns:
  • string A valid querystring (without the prefixing '?')
See also:

get_hostname

Retrieves the hostname of the local machine
Returns:
  • string The hostname

is_array

Checks if a table is an array and not an associative array. * NOTE * string-keys containing integers are considered valid array entries!
Parameters:
  • t The table to check
Returns:
  • Returns true if the table is an array, false otherwise

load_module_if_exists

Try to load a module. Will not throw an error if the module was not found, but will throw an error if the loading failed for another reason (eg: syntax error).
Parameters:
  • module_name Path of the module to load (ex: kong.plugins.keyauth.api).
Returns:
  • success A boolean indicating whether the module was found.
  • module The retrieved module.

random_string

Generates a random unique string
Returns:
  • string The random string (a uuid without hyphens)

table_contains

Checks if a value exists in a table.
Parameters:
  • arr The table to use
  • val The value to check
Returns:
  • Returns true if the table contains the value, false otherwise

table_merge

Merges two table together. A new table is created with a non-recursive copy of the provided tables
Parameters:
  • t1 The first table
  • t2 The second table
Returns:
  • The (new) merged table

table_size

Calculates a table size. All entries both in array and hash part.
Parameters:
  • t The table to use
Returns:
  • number The size