From 257b5cd517a615282e3bcc5d9d765b8a049e6fef Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 20 Feb 2025 15:58:50 -0500 Subject: [PATCH] docs: lua warn about first run checks Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- docs/lua-records/functions.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/lua-records/functions.rst b/docs/lua-records/functions.rst index 45a63a1c25..d0248a88fe 100644 --- a/docs/lua-records/functions.rst +++ b/docs/lua-records/functions.rst @@ -43,6 +43,14 @@ Functions available Record creation functions ~~~~~~~~~~~~~~~~~~~~~~~~~ + .. _if-first-run: + +.. warning:: + For functions that require network traffic ``if...(..., addresses[...])``, + the first time they're called, they effectively treat all addresses as + failing which means that whatever fallback behavior is used will apply to + that first resolution. + .. function:: ifportup(portnum, addresses[, options]) Simplistic test to see if an IP address listens on a certain port. This will @@ -52,8 +60,8 @@ Record creation functions list IPv4 addresses on an AAAA record, or IPv6 addresses on an A record. Will return a single address from the set of available addresses. If - no address is available, will return a random element of the set of - addresses supplied for testing. + no address is available (but also :ref:`on the first run `), + will return a random element of the set of addresses supplied for testing. :param int portnum: The port number to test connections to. :param {str} addresses: The list of addresses to check connectivity for. @@ -72,7 +80,8 @@ Record creation functions .. function:: ifurlup(url, addresses[, options]) More sophisticated test that attempts an actual http(s) connection to - ``url``. In addition, a list of sets of IP addresses can be supplied. The + ``url`` (but results are not used :ref:`on the first run `). + In addition, a list of sets of IP addresses can be supplied. The first set with at least one available address is selected. The ``selector`` then selects from the subset of available addresses of the selected set. An URL is considered available if the HTTP response code is 200 and optionally if -- 2.47.2