# # Copyright (c) Carlos Abalde # # You're free to use and distribute this under terms in the # LICENSE file. # $Module cfg 3 CFG VMOD $ABI strict DESCRIPTION =========== VMOD useful to access to contents of environment variables and local or remote configuration files from VCL. $Event event_function $Object env() Description Extracts existing environment variables and creates a new instance. Beware environment variables are internally cached. This cache is populated when creating a new instance and it's never refreshed. $Method STRING .dump(BOOL stream=0, STRING prefix="") Arguments stream: if enabled, the JSON object will be streamed as a synthetic response. prefix: if specified, the JSON object will only contain the variables that start with that prefix. Description Returns a string representation of a JSON object containing all variables. If called during ``vcl_synth`` or ``vcl_backend_error`` with the ``stream`` argument enabled, this function will return an empty string and behave as a call to the ``synthetic`` VCL function with the JSON object as input. This highly reduces the amount of required workspace memory, specially for large JSON objects. $Method BOOL .is_set(STRING name) Arguments name: name of the environment variable. Description Checks if an environment variable is set. $Method STRING .get(STRING name, STRING fallback="") Arguments name: name of the environment variable. fallback: value to be returned if the environment variable does not exist. Description Gets the value of an environment variable. $Object file( STRING location, STRING backup="", INT period=60, BOOL ignore_load_failures=1, INT curl_connection_timeout=0, INT curl_transfer_timeout=0, BOOL curl_ssl_verify_peer=0, BOOL curl_ssl_verify_host=0, STRING curl_ssl_cafile="", STRING curl_ssl_capath="", STRING curl_proxy="", ENUM { ini, json } format="ini", STRING name_delimiter=":", STRING value_delimiter=";") Arguments location: path of the file. The following schemes are supported: ``file://``, ``http://`` and ``https://``. If not specified ``file://`` is assumed. backup: when this option is used, you have to specify where to save the backup file. period: how frequently (seconds) contents of the file are reloaded (0 means disabling periodical reloads). ignore_load_failures: if enabled and the initial file loading fails (parse error, timeouts, etc.), the VCL objet is still created. curl_connection_timeout: connection timeout (milliseconds; 0 means no timeout). curl_transfer_timeout: transfer timeout (milliseconds; 0 means no timeout). curl_ssl_verify_peer: if enabled the peer's SSL certificate will be verified. curl_ssl_verify_host: if enabled the certificate's name will be verified against host. curl_ssl_cainfo: path to CA bundle (empty string means no CA bundle). curl_ssl_capath: directory holding CA certificates (empty string means no CA path). curl_proxy: HTTP proxy to be used (empty string means no proxy). format: format of the file. name_delimiter: delimiter to be used if flattening the keys namespace is required. value_delimiter: delimiter to be used if flattening a list of values is required. Beware the VMOD ignores JSON arrays. Description Parses the file and creates a new instance. Beware contents of the file are internally cached. This cache is refreshed on every VCL WARM event received by the VMOD and every ``period`` seconds (if ``period`` > 0). $Method BOOL .reload() Description Reloads contents of the file. A ``False`` value is returned on failure. $Method STRING .dump(BOOL stream=0, STRING prefix="") Arguments stream: if enabled, the JSON object will be streamed as a synthetic response. prefix: if specified, the JSON object will only contains the variables that start with that prefix. Description Returns a string representation of a JSON object containing all variables. If called during ``vcl_synth`` or ``vcl_backend_error`` with the ``stream`` argument enabled, this function will return an empty string and behave as a call to the ``synthetic`` VCL function with the JSON object as input. This highly reduces the amount of required workspace memory, specially for large JSON objects. $Method VOID .inspect() Description This function may be called during ``vcl_synth`` or ``vcl_backend_error`` and it will behave as a call to the ``synthetic`` VCL function with current contents of the file as input. $Method BOOL .is_set(STRING name) Arguments name: name of the -eventually flattened- key. Description Checks if a key is set. $Method STRING .get(STRING name, STRING fallback="") Arguments name: name of the -eventually flattened- key. fallback: value to be returned if the key does not exist. Description Gets the value of a key. $Object rules( STRING location, STRING backup="", INT period=60, BOOL ignore_load_failures=1, INT curl_connection_timeout=0, INT curl_transfer_timeout=0, BOOL curl_ssl_verify_peer=0, BOOL curl_ssl_verify_host=0, STRING curl_ssl_cafile="", STRING curl_ssl_capath="", STRING curl_proxy="") Description Parses the file and creates a new instance. See ``cfg.file()`` for details. $Method BOOL .reload() Description Reloads contents of the file. A ``False`` value is returned on failure. $Method VOID .inspect() Description This function may be called during ``vcl_synth`` or ``vcl_backend_error`` and it will behave as a call to the ``synthetic`` VCL function with current contents of the rules file as input. $Method STRING .get(STRING value, STRING fallback="") Arguments value: value to be matched against the collection of rules. fallback: value to be returned if a match is not found. Description Gets the result of executing the pattern matching logic. $Object script( STRING location="", STRING backup="", INT period=60, BOOL ignore_load_failures=1, ENUM { lua, javascript } type="lua", INT max_engines=128, INT max_cycles=0, INT min_gc_cycles=100, BOOL enable_sandboxing=1, INT lua_gc_step_size=100, BOOL lua_remove_loadfile_function=1, BOOL lua_remove_dotfile_function=1, BOOL lua_load_package_lib=0, BOOL lua_load_io_lib=0, BOOL lua_load_os_lib=0, INT curl_connection_timeout=0, INT curl_transfer_timeout=0, BOOL curl_ssl_verify_peer=0, BOOL curl_ssl_verify_host=0, STRING curl_ssl_cafile="", STRING curl_ssl_capath="", STRING curl_proxy="") Arguments location: path of the file (as described in ``cfg.file()``) containing the script implementation. If not provided, the script implementation should be provided to the ``.init()`` method. engine: type of scripting engine to be used. max_engines: the VMOD creates one pool of scripting engines per VCL object. This option sets the maximum number of engines in each pool. All Varnish worker threads using the same object will share engines in these pools. Pools are not shared between VCL objects. max_cycles: discard scripting engines after this number of script executions (0 means disabling periodical discards). min_gc_cycles: call to the scripting engine garbage collector after this number of script executions. enable_sandboxing: enforce best-effort sandboxing in order to avoid most common mistakes like creation of implicit globals. Beware this should be disabled for complex scripts if global (i.e. per scripting engine) data-sharing is needed. lua_gc_step_size: scripting engines implement incremental garbage collection (see ``LUA_GCSTEP`` in ``lua_gc()``). This parameter controls the step size. lua_remove_loadfile_function: disable ``loadfile`` function. lua_remove_dotfile_function: disable ``dotfile`` function. lua_load_package_lib: allow access to the ``package`` library. lua_load_io_lib: allow access to the ``io`` library. lua_load_os_lib: allow access to the ``os`` library. Description Parses the file (if provided) and creates a new instance. See ``cfg.file()`` for details about undocumented arguments. $Method BOOL .reload() Description Reloads contents of the file. A ``False`` value is returned on failure. $Method VOID .inspect(PRIV_TASK) Description This function may be called during ``vcl_synth`` or ``vcl_backend_error`` and it will behave as a call to the ``synthetic`` VCL function with current contents of the loaded script (inline script or file) as input. $Method VOID .init(PRIV_TASK, STRING code="") Arguments code: implementation of the script to be executed. If not provided, the implementation provided during object instantiation will be used. Description Gets ready for a execution of the script. Arguments should be enqueued separately calling one or more times to the ``.push()`` method. $Method VOID .push(PRIV_TASK, STRING arg) Arguments arg: argument for a previously initialized script. Description Provides an argument to a previously initialized script. $Method VOID .execute(PRIV_TASK, BOOL gc_collect=0, BOOL flush_jemalloc_tcache=1) Arguments gc_collect: performs a full garbage-collection cycle once execution is completed. flush_jemalloc_tcache: flush jemalloc tcache once execution is completed. Description Executes a previously initialized script. $Method BOOL .result_is_error(PRIV_TASK) Return value TRUE if a previously executed script using ``.execute()`` returned an error value. $Method BOOL .result_is_nil(PRIV_TASK) Return value TRUE if a previously executed script using ``.execute()`` returned a nil value. $Method BOOL .result_is_null(PRIV_TASK) Description Alias of ``.result_is_nil()``. $Method BOOL .result_is_boolean(PRIV_TASK) Return value TRUE if a previously executed script using ``.execute()`` returned a boolean value. $Method BOOL .result_is_number(PRIV_TASK) Return value TRUE if a previously executed script using ``.execute()`` returned a number value. $Method BOOL .result_is_string(PRIV_TASK) Return value TRUE if a previously executed script ``.execute()`` returned a string value. $Method BOOL .result_is_table(PRIV_TASK) Return value TRUE if a previously executed script using ``.execute()`` returned an table value. $Method BOOL .result_is_array(PRIV_TASK) Description Alias of ``.result_is_table()``. $Method STRING .get_result(PRIV_TASK) Return value A string representation of the result value of a previously executed script using ``.execute()``. Description Do not use this function to access to table results. $Method BOOL .get_boolean_result(PRIV_TASK) Return value If a previously executed script using ``.execute()`` returned a boolean value, this function returns a boolean representation of that value. $Method REAL .get_decimal_result(PRIV_TASK) Return value If a previously executed script using ``.execute()`` returned a decimal value, this function returns a decimal representation of that value. $Method INT .get_integer_result(PRIV_TASK) Return value If a previously executed script using ``.execute()`` returned an integer value, this function returns a integer representation of that value. $Method STRING .get_string_result(PRIV_TASK) Return value If a previously executed script using ``.execute()`` returned a string value, this function returns a string representation of that value. $Method INT .get_table_result_length(PRIV_TASK) Return value If a previously executed script using ``.execute()`` returned a table value, this function returns the number of elements in that table. $Method INT .get_array_result_length(PRIV_TASK) Description Alias of ``.get_table_result_length()``. $Method BOOL .table_result_is_error(PRIV_TASK, INT index) Arguments index: index in the table result. Return value If a previously executed script using ``.execute()`` returned a table value, this function returns TRUE if the nth element in that table is an error value (nested tables are not supported). $Method BOOL .array_result_is_error(PRIV_TASK, INT index) Description Alias of ``.table_result_is_error()``. $Method BOOL .table_result_is_nil(PRIV_TASK, INT index) Arguments index: index in the table result. Return value If a previously executed script using ``.execute()`` returned a table value, this function returns TRUE if the nth element in that table is a nil value (nested tables are not supported). $Method BOOL .array_result_is_null(PRIV_TASK, INT index) Description Alias of ``.table_result_is_nil()``. $Method BOOL .table_result_is_boolean(PRIV_TASK, INT index) Arguments index: index in the table result. Return value If a previously executed script using ``.execute()`` returned a table value, this function returns TRUE if the nth element in that table is a boolean value (nested tables are not supported). $Method BOOL .array_result_is_boolean(PRIV_TASK, INT index) Description Alias of ``.table_result_is_boolean()``. $Method BOOL .table_result_is_number(PRIV_TASK, INT index) Arguments index: index in the table result. Return value If a previously executed script using ``.execute()`` returned a table value, this function returns TRUE if the nth element in that table is a number value (nested tables are not supported). $Method BOOL .array_result_is_number(PRIV_TASK, INT index) Description Alias of ``.table_result_is_number()``. $Method BOOL .table_result_is_string(PRIV_TASK, INT index) Arguments index: index in the table result. Return value If a previously executed script using ``.execute()`` returned a table value, this function returns TRUE if the nth element in that table is a string value (nested tables are not supported). $Method BOOL .array_result_is_string(PRIV_TASK, INT index) Description Alias of ``.table_result_is_string()``. $Method BOOL .table_result_is_table(PRIV_TASK, INT index) Arguments index: index in the table result. Return value If a previously executed script using ``.execute()`` returned a table value, this function returns TRUE if the nth element in that table is a table value (nested tables are not supported). $Method BOOL .array_result_is_array(PRIV_TASK, INT index) Description Alias of ``.table_result_is_table()``. $Method STRING .get_table_result_value(PRIV_TASK, INT index) Arguments index: index in the table result. Return value If a previously executed script using ``.execute()`` returned a table value, this function returns a string representation of the nth element in that table (nested table are not supported). $Method STRING .get_array_result_value(PRIV_TASK, INT index) Description Alias of ``.get_table_result_value()``. $Method VOID .free_result(PRIV_TASK) Description Frees memory internally used by a previously executed script using ``.execute()``. It's recommended to use this function, but if not called this will be handled automatically during the next call to ``.init()`` using the same object. $Method STRING .stats() Description Returns internal stats represented as a JSON string. $Method INT .counter(STRING name) Arguments name: name of the counter. Description Returns internal counter.